@tapsilat/tapsilat-js 2026.7.7 → 2026.10.26

package/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2026.10.26] - 2026-10-26
+
+### Added
+- `createElementsSession`, `getElementsSession` and `cancelElementsSession` for Tapsilat Elements sessions (`POST /elements/sessions`, `GET /elements/sessions/{id}`, `POST /elements/sessions/{id}/cancel`), with the `ElementsSessionCreateRequest`, `ElementsSessionCreateResponse`, `ElementsSession`, `ElementsCardSummary` and `ElementsSessionError` types and the `ElementsSessionPurpose`, `ElementsSessionStatus`, `ElementsTokenizeMode` and `ElementsCardBrand` constants. In Node.js the created session prints its `client_secret` as `[redacted]`; `JSON.stringify` keeps it.
+- `TapsilatError.retryable`, set when the API error says the request can be retried.
+
+### Fixed
+- Errors nested as `{"error": {"code", "message", "retryable"}}` set `message`, `apiCode` and `retryable` from that object instead of a message of `[object Object]`.
+
 ## [2025.12.5] - 2025-12-05
 
 ### Added

package/README.md

@@ -75,6 +75,7 @@ console.log("Order status:", status.status);
 - Complete payment lifecycle management
 - Multi-currency support (TRY, USD, EUR, GBP)
 - Advanced filtering and pagination
+- Tapsilat Elements sessions for the native Android and iOS card sheet
 
 ### Payment Term Management
 - Create and manage installment plans
@@ -101,19 +102,7 @@ console.log("Order status:", status.status);
 
 ## SDK Compatibility
 
-This JavaScript SDK provides full feature parity with Tapsilat's Python and .NET SDKs:
-
-| Feature Category | JavaScript | Python | .NET | 
-|-----------------|------------|--------|------|
-| Order Management | Yes | Yes | Yes |
-| Payment Terms | Yes | Yes | Yes |
-| System Utilities | Yes | Yes | Yes |
-| Organization | Yes | Yes | Yes |
-| GSM Validation | Yes | Yes | Yes |
-| Installment Validation | Yes | Yes | Yes |
-| Webhook Verification | Yes | No | No |
-| TypeScript Support | Yes | No | Yes |
-| Health Monitoring | Yes | No | No |
+All Tapsilat SDKs (Go, JavaScript, Python, .NET, Kotlin, Rust, Swift and Zig) target the same panel REST API, so orders, payment terms, subscriptions, organization settings, submerchants, VPOS, card tokenization, card installments and the marketplace API behave the same in each. Webhook signature verification and the health check are additional helpers in this SDK.
 
 ---
 
@@ -152,7 +141,7 @@ console.log('Order status:', order.status);
 #### Check Order Status
 ```typescript
 const status = await tapsilat.getOrderStatus('order-reference-id');
-if (status.status === 'completed') {
+if (OrderStatus.isPaid(status.status)) {
   console.log('Payment successful!');
 }
 ```
@@ -193,6 +182,22 @@ transactions.forEach(tx => {
 });
 ```
 
+#### Charge Order
+```typescript
+const chargeResult = await tapsilat.chargeOrder({
+  order_reference_id: 'order-reference-id'
+});
+console.log('Order charged:', chargeResult);
+```
+
+#### Get Order Payments
+`getAllOrdersPayments` is deprecated: the API has no route for it. List one order's payments with `getOrderPayments` and an order ID, reference ID or conversation ID.
+
+```typescript
+const payments = await tapsilat.getOrderPayments({ order_reference_id: 'order-reference-id' });
+console.log('Merchant net amount:', payments.total_merchant_net_amount);
+```
+
 #### Get Checkout URL
 ```typescript
 const checkoutUrl = await tapsilat.getCheckoutUrl('order-reference-id');
@@ -225,55 +230,65 @@ console.log('Full refund processed:', fullRefund.amount);
 ### Webhook Handling
 
 #### Verify Webhook Signature
+Tapsilat signs every callback it sends to your callback URLs, and to an order's `payment_success_url` and `payment_failure_url`, with the webhook secret from the panel's callback settings. The `Tapsilat-Signature` header looks like `t=1726480000,v1=5257a8…`: `v1` is the hex HMAC-SHA256 of the timestamp, a dot and the raw body.
+
+`verifyWebhook` checks it in constant time and rejects a timestamp more than 5 minutes from the server clock, so a captured callback cannot be replayed. Pass the raw body (a string or a `Buffer`), not re-encoded JSON. It resolves to `false` when the header is missing, malformed, stale or wrong.
 ```typescript
 import express from 'express';
+import { WebhookEvent, WEBHOOK_SIGNATURE_HEADER } from '@tapsilat/tapsilat-js';
 
 const app = express();
-app.use(express.raw({ type: 'application/json' }));
 
-app.post('/webhooks/tapsilat', async (req, res) => {
-  const payload = req.body.toString();
-  const signature = req.headers['x-tapsilat-signature'];
-  
+app.post('/webhooks/tapsilat', express.raw({ type: '*/*' }), async (req, res) => {
   const isValid = await tapsilat.verifyWebhook(
-    payload, 
-    signature, 
-    process.env.WEBHOOK_SECRET
+    req.body, // the raw body as a Buffer
+    req.get(WEBHOOK_SIGNATURE_HEADER), // "Tapsilat-Signature"
+    process.env.TAPSILAT_WEBHOOK_SECRET!
   );
-  
   if (!isValid) {
-    return res.status(401).json({ error: 'Invalid signature' });
+    return res.sendStatus(400);
   }
-  
-  const event = JSON.parse(payload);
-  
-  switch (event.type) {
-    case 'order.completed':
-      console.log('Order completed:', event.data.reference_id);
-      // Process successful payment
-      break;
-    case 'order.failed':
-      console.log('Order failed:', event.data.reference_id);
-      // Handle failed payment
-      break;
+
+  const event = WebhookEvent.fromPayload(req.body);
+  event.type;           // "order_lite" (the default), "order", "order_payment_detail", ...
+  event.referenceId;    // the order's reference ID, whatever the callback type
+  event.conversationId;
+  event.status;         // e.g. "Paid", when the callback type carries a status
+
+  if (event.isPaid()) {
+    // fulfil the order
   }
-  
-  res.json({ received: true });
+  res.sendStatus(200);
 });
 ```
 
+A different tolerance in seconds can be passed as `{ tolerance }` in the fourth argument (`0` disables the timestamp check), and `{ now }` sets the Unix time to compare with. A bare hex HMAC of the body, with or without a `sha256=` prefix, is still accepted for signatures made the way earlier SDK versions documented.
+
+#### Order Statuses
+`OrderStatus` has the numeric status codes that callbacks carry, the names `getOrderStatus()` returns, and the groups most integrations need:
+```typescript
+import { OrderStatus } from '@tapsilat/tapsilat-js';
+
+const { status } = await tapsilat.getOrderStatus(referenceId); // e.g. "Waiting for payment"
+
+OrderStatus.isPaid(status);     // Paid, Completed, Sub merchant payment approved
+OrderStatus.isFailed(status);   // Cancelled, Fraud, Rejected, Failure, Expired, Terminated
+OrderStatus.isRefunded(status); // Refunded, Partially refunded
+OrderStatus.code(status);       // 7; also accepts "7" or 7
+```
+
 ### Payment Term Management
 
 #### Create Payment Term
 ```typescript
+// order_id is the order's ID (order_id from createOrder), not its reference ID
 const paymentTerm = await tapsilat.createOrderTerm({
-  order_id: 'order-reference-id',
+  order_id: createdOrder.order_id,
   term_reference_id: 'term-001',
   amount: 250.00,
-  due_date: '2024-12-31',
+  due_date: '2024-12-31', // YYYY-MM-DD
   term_sequence: 1,
   required: true,
-  status: 'pending',
   data: 'First installment'
 });
 console.log('Payment term created:', paymentTerm.term_reference_id);
@@ -281,11 +296,14 @@ console.log('Payment term created:', paymentTerm.term_reference_id);
 
 #### Update Payment Term
 ```typescript
+// The update replaces the term, so send every field rather than only the changed ones
 const updatedTerm = await tapsilat.updateOrderTerm({
   term_reference_id: 'term-001',
+  term_sequence: 1,
+  required: true,
   amount: 275.00,
   due_date: '2025-01-15',
-  status: 'updated'
+  status: 'pending'
 });
 console.log('Payment term updated:', updatedTerm.status);
 ```
@@ -293,6 +311,7 @@ console.log('Payment term updated:', updatedTerm.status);
 #### Delete Payment Term
 ```typescript
 const deletedTerm = await tapsilat.deleteOrderTerm({
+  order_id: createdOrder.order_id,
   term_reference_id: 'term-001'
 });
 console.log('Payment term deleted:', deletedTerm.term_reference_id);
@@ -301,14 +320,16 @@ console.log('Payment term deleted:', deletedTerm.term_reference_id);
 #### Refund Payment Term
 ```typescript
 const termRefund = await tapsilat.refundOrderTerm({
-  term_id: 'term-001',
-  amount: 100.00,
-  reference_id: 'refund-ref-123'
+  term_id: 'term-id',              // the term's ID
+  reference_id: 'order-reference-id', // the order's reference ID
+  amount: 100.00
 });
 console.log('Term refund processed:', termRefund.refund_id);
 ```
 
 #### Terminate Payment Term
+`terminateOrderTerm` is deprecated: the API has no payment term termination route. Delete the term with `deleteOrderTerm`, or end the whole order with `terminateOrder`.
+
 ```typescript
 const terminatedTerm = await tapsilat.terminateOrderTerm({
   term_reference_id: 'term-001',
@@ -478,7 +499,21 @@ console.log('Organization Settings:', settings);
 #### Get Currency Presets
 ```typescript
 const presets = await tapsilat.getOrganizationCurrencyPresets();
-console.log('Available currencies:', presets);
+console.log('Available currencies:', presets.items);
+```
+
+#### Organization Management
+```typescript
+// Create Currency
+const newCurrency = await tapsilat.createOrganizationCurrency({
+  currency_code: 'EUR'
+});
+
+// Get Partners
+const partners = await tapsilat.getOrganizationPartners();
+
+// Get Limits
+const limits = await tapsilat.getOrganizationLimitsById('org-uuid', { currency: 'TRY' });
 ```
 
 #### Get Suborganization Details
@@ -492,6 +527,7 @@ console.log('Suborganization Name:', suborg.name);
 #### Get System Endpoints
 ```typescript
 // Fetch various system configurations
+const config = await tapsilat.getSystemConfig();
 const errorCodes = await tapsilat.getSystemErrorCodes();
 const productTypes = await tapsilat.getSystemProductTypes();
 const transactionStatuses = await tapsilat.getSystemTransactionStatuses();
@@ -520,6 +556,141 @@ const updateResult = await tapsilat.orderRelatedUpdate(
 console.log('Related order updated:', updateResult.success);
 ```
 
+### Card Installments and Charging
+
+```typescript
+const options = await tapsilat.getCardInstallments({
+  bin: '54066200',
+  amount: 100,
+  currency: 'TRY',
+});
+// options.installments lists each installment count with its commission rate and monthly payment
+
+const table = await tapsilat.getInstallmentTable({ amount: 100, currency: 'TRY' });
+// table.groups lists installment rows per bank card program
+
+const charge = await tapsilat.chargeOrder({ order_reference_id: 'order-reference-id' });
+if (!charge.isSuccess) {
+  // The request succeeded but the charge did not; inspect charge.errorCode and charge.message
+}
+```
+
+### Submerchants, VPOS and Tokenization
+
+Grouped services cover the remaining management APIs. Currency fields accept a currency UUID or an organization unit such as `TRY`; the server resolves units.
+
+```typescript
+await tapsilat.submerchants.createSubmerchant({
+  locale: 'tr',
+  conversation_id: 'seller-1',
+  name: 'Example Ltd',
+  email: 'finance@example.test',
+  gsm_number: '905551112233',
+  sub_merchant_type: 'PRIVATE_COMPANY',
+  tax_number: '1234567890',
+  currency_id: 'TRY',
+});
+
+const posList = await tapsilat.vpos.listVpos({ page: 1, per_page: 20 });
+const card = await tapsilat.tokenization.tokenizeCard({
+  card_number: '4111111111111111',
+  holder_name: 'John Doe',
+  expiry_month: '12',
+  expiry_year: '30',
+  cvv: '123',
+  user_id: 'customer-1',
+});
+```
+
+`updateVpos` and `updateSubmerchant` replace the stored record: read it first and send every field back. For example, leaving out `failover` or `tls` stores `false`.
+
+### Marketplace
+
+`tapsilat.marketplace` uses the API version 2 routes, derived from your `baseURL`. Revisions are opaque strings: pass them back exactly as received.
+
+```typescript
+const payout = await tapsilat.marketplace.getMarketplacePayout(payoutId);
+if (payout.eligibility_status === 'eligible' && payout.release_status === 'awaiting_approval') {
+  await tapsilat.marketplace.approveMarketplacePayouts({ ids: [payout.id!] });
+}
+
+await tapsilat.marketplace.runMarketplacePayoutOperation(payoutId, {
+  kind: 'update_item',
+  idempotency_key: 'booking-123-allocation-change-1',
+  revision: payout.revision!,
+  seller_reference: seller.routing_reference,
+  net_amount: '60.25',
+});
+```
+
+Approval policies need a currency UUID; `createMarketplaceApprovalPolicy` and `updateMarketplaceApprovalPolicy` resolve units such as `TRY` for you, and `tapsilat.resolveCurrencyId('TRY')` exposes the same lookup.
+
+### Tapsilat Elements Sessions
+
+Tapsilat Elements is the native Android and iOS card sheet. Your backend creates a session with its secret API key and passes only the session's `client_secret` to the app, which opens the sheet with it. Card data goes from the sheet to Tapsilat encrypted and never reaches your backend.
+
+#### Create an Elements Session
+```typescript
+import { ElementsSessionPurpose } from '@tapsilat/tapsilat-js';
+
+const session = await tapsilat.createElementsSession({
+  purpose: ElementsSessionPurpose.PAY,
+  order_reference_id: order.reference_id,
+  save_card: true,
+});
+
+// Return session.id and session.client_secret to your app. Do not log or store the secret.
+res.json({ id: session.id, client_secret: session.client_secret });
+```
+
+A `pay` session needs `order_reference_id`. A `tokenize` session saves a card for `user_id`, with `mode` set to `ElementsTokenizeMode.SECURE` (3D Secure), `HALF_SECURE` or `NON_SECURE`:
+```typescript
+import { ElementsSessionPurpose, ElementsTokenizeMode } from '@tapsilat/tapsilat-js';
+
+const session = await tapsilat.createElementsSession({
+  purpose: ElementsSessionPurpose.TOKENIZE,
+  user_id: 'customer-1',
+  user_email: 'customer@example.test',
+  mode: ElementsTokenizeMode.SECURE,
+});
+```
+
+#### Get the Session Outcome
+Read the outcome on your backend before fulfilling, instead of trusting what the app reports:
+```typescript
+import { ElementsSessionStatus } from '@tapsilat/tapsilat-js';
+
+const outcome = await tapsilat.getElementsSession(sessionId);
+if (outcome.status === ElementsSessionStatus.SUCCEEDED) {
+  // fulfil the order; outcome.card holds the brand, last4 and expiry
+} else if (outcome.status === ElementsSessionStatus.FAILED) {
+  // outcome.last_error?.code says why, for example "card_declined"
+}
+```
+
+#### Cancel an Elements Session
+```typescript
+const canceled = await tapsilat.cancelElementsSession(sessionId);
+```
+This cancels a session that is still waiting for a card. A session that is confirming or has completed comes back unchanged, so check `canceled.status`.
+
+The client secret is returned only by `createElementsSession`. In Node.js, `console.log` and `util.inspect` print it as `[redacted]`, and `JSON.stringify` keeps it so you can still send it to the app; a copy made with the spread operator prints it in full. `status`, `purpose` and `card.brand` are plain strings, so compare them with `ElementsSessionStatus`, `ElementsSessionPurpose` and `ElementsCardBrand`. Elements errors carry a stable `apiCode` (for example `elements_not_enabled` with HTTP 403, `session_not_found` with HTTP 404) and `retryable`, which is `true` for a temporary failure such as HTTP 503 `unavailable`:
+```typescript
+import { TapsilatError } from '@tapsilat/tapsilat-js';
+
+try {
+  await tapsilat.getElementsSession(sessionId);
+} catch (error) {
+  if (error instanceof TapsilatError && error.retryable) {
+    // try again later
+  }
+}
+```
+
+### Error Details
+
+Failed requests throw a `TapsilatError` (or a subclass). Besides `message` and `code`, it carries `statusCode`, the API's own `apiCode` and `apiStatus`, per-field validation `errors`, `retryable`, and the `rawBody`. Elements routes nest the error as `{"error": {"code": "...", "message": "...", "retryable": true}}`; `apiCode`, `message` and `retryable` are read from that object. Most "not found" errors arrive as HTTP 400, and rejected state changes (for example approving an ineligible payout) as HTTP 424. A successful status with an HTML body, which a deployment serving the panel UI returns for unknown routes, raises a `TapsilatError` with code `UNEXPECTED_RESPONSE`.
+
 ### Health Monitoring
 
 #### API Health Check