@payabli/component-contracts 0.1.2 → 0.2.0

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Payabli Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -24,6 +24,528 @@ pnpm add @payabli/component-contracts
 Schemas are zod v4 mini and the runtime is bundled. Consumers on zod 3.25 or
 later resolve the types through `zod/v4/mini`.
 
+## PayIn contract summary
+
+Create the session on your server. Pass only presentation settings to the browser.
+PayIn does not accept `prefill` in SDK create/update options or React props.
+Prefill remains a generic capability that other components may support through `PREFILL_SET` and `PREFILL_REQUEST`.
+
+### Session/init config
+
+The request is `POST /api/v2/{slug}/Session/init` with `platform: 'Web'`, `entryPoint`, `allowedParentOrigins`, and `components`.
+`GET /api/v2/Session/bootstrap` returns each component's config unchanged.
+Tenant identity, operation, payment amounts, customer data, and invoice data come only from the server session.
+The browser submit payload contains payment credentials, capture results, and the selected method, not business configuration.
+
+The API's generated SDK owns session types. Browser `payinOptionsSchema` contains only `showSubmitButton`, `initialMethod`, and `methodOrder`.
+
+```js
+components: [
+  {
+    type: 'payin',
+    config: {
+      operation: 'pay',
+      methods: ['card', 'ach', 'check', 'applepay', 'googlepay'],
+      acceptedCardBrands: ['Visa', 'Mastercard'],
+      defaults: { achAccountType: 'checking' },
+      ach: { allowedAccountTypes: ['checking', 'savings'] },
+      fields: {
+        card: {
+          holderName: 'required',
+          cvv: 'required',
+          postalCode: 'required',
+        },
+      },
+      forceCustomerCreation: false,
+      paymentDetails: { totalAmount: 12.34, serviceFee: 0.34, currency: 'USD' },
+      customerData: { firstName: 'Jane', lastName: 'Doe' },
+      invoiceData: { invoiceNumber: 'INV-1001' },
+      saveIfSuccess: false,
+      idempotencyKey: 'partner-key-123', // Optional. Omit for a generated key.
+    },
+  },
+];
+```
+
+- `paymentDetails` is required for `pay` and `auth`. `totalAmount` must exceed zero and already includes `serviceFee`. Never add the fee again.
+- `serviceFee` is optional. If present, it must be at least zero and less than `totalAmount`.
+- `currency` is optional and accepts only `USD` or `CAD`. Omitted currency displays as USD and stays omitted in the API request.
+- `customerData` is required and non-null for `pay` and `auth`. An explicit `{}` is allowed. `invoiceData` remains optional. Both pass through unchanged.
+- `saveIfSuccess` defaults to `false`. A value of `true` sets `paymentMethod.saveIfSuccess` for card, ACH, or wallets. Check submissions reject it.
+
+For `tokenize`, omit `paymentDetails` and `invoiceData`. Do not set `saveIfSuccess` to `true`.
+The session API rejects unknown fields. It does not trim, change case, infer names, or merge addresses in customer or invoice data.
+The session config rejects `amount`, `billingAddress`, and `requiredFields`. There are no compatibility aliases.
+
+#### Payment, customer, and invoice data
+
+`operation` is `pay`, `auth`, or `tokenize`. `methods` contains only methods supported by the paypoint and operation.
+An empty methods list uses paypoint capabilities, filtered by the operation. Session creation fails when no supported method remains.
+`acceptedCardBrands` stays server-owned. The exported `CARD_BRANDS` tuple lists the card brand vocabulary.
+`defaults.achAccountType` supplies the ACH default. The ACH rules below constrain its value.
+
+These are the supported nested fields. Except for `paymentDetails.totalAmount`, each nested field is optional.
+Use the API's generated SDK for session types, not a second browser-side session schema.
+
+```js
+paymentDetails: {
+  totalAmount: 12.34, serviceFee: 0.34, currency: 'USD',
+  checkNumber: '1001', checkUniqueId: 'check-1001',
+  orderDescription: 'Order', orderId: '1001', orderIdAlternative: 'ALT-1001',
+  paymentDescription: 'Payment', settlementDescriptor: 'STORE', groupNumber: '1',
+  unbundled: false,
+  categories: [{ label: 'Item', description: 'Item details', amount: 1, qty: 1 }],
+  splitFunding: [{
+    recipientEntryPoint: 'recipient', accountId: 'account', description: 'Share', amount: 1,
+  }],
+}
+```
+
+`categories[].amount` and `splitFunding[].amount` must exceed zero when present.
+The displayed total and wallet sheet amount are `totalAmount`. Wallet currency is `currency ?? 'USD'`.
+RDC capture supplies `checkNumber`, `checkUniqueId`, and `checkImage`, overriding configured check identifiers.
+All other configured payment details survive. The session rejects `checkImage`, `source`, and `payabliTransId` inside `paymentDetails`.
+The app keeps its fixed top-level `source`. It gets `entryPoint` from the session.
+
+```js
+customerData: {
+  customerId: 123, customerStatus: 1, firstName: 'Jane', lastName: 'Doe',
+  company: 'Example', customerNumber: 'C-1001',
+  billingAddress1: '123 Main St', billingAddress2: 'Unit 1', billingCity: 'Austin',
+  billingState: 'TX', billingZip: '78701', billingCountry: 'US',
+  billingPhone: '5125550100', billingEmail: 'jane@example.com',
+  shippingAddress1: '123 Main St', shippingAddress2: 'Unit 1', shippingCity: 'Austin',
+  shippingState: 'TX', shippingZip: '78701', shippingCountry: 'US',
+  additionalData: { key: 'value' }, identifierFields: ['email'],
+}
+```
+
+An explicit customer or invoice `{}` stays `{}`. An absent optional object stays absent in the API request.
+The app does not infer customer names from holder fields or merge card ZIP codes or wallet contacts into customer data.
+Unknown properties in these objects and their nested arrays produce a clear HTTP 400 instead of silent removal.
+
+```js
+invoiceData: {
+  invoiceNumber: 'INV-1001', invoiceDate: '2026-09-10', invoiceDueDate: '2026-10-10',
+  invoiceEndDate: '2026-10-10', invoiceStatus: 1, invoiceType: 0,
+  frequency: 'onetime', paymentTerms: 'Net 30', termsConditions: 'Terms', notes: 'Note',
+  tax: 0, discount: 0, invoiceAmount: 12.34, freightAmount: 0, dutyAmount: 0,
+  purchaseOrder: 'PO-1001', firstName: 'Jane', lastName: 'Doe', company: 'Example',
+  shippingAddress1: '123 Main St', shippingAddress2: 'Unit 1', shippingCity: 'Austin',
+  shippingState: 'TX', shippingZip: '78701', shippingCountry: 'US',
+  shippingEmail: 'jane@example.com', shippingPhone: '5125550100', shippingFromZip: '78701',
+  summaryCommodityCode: '1000',
+  items: [{
+    itemProductCode: 'SKU-1', itemProductName: 'Item', itemDescription: 'Item details',
+    itemCommodityCode: '1000', itemUnitOfMeasure: 'each', itemCost: 1, itemQty: 1,
+    itemMode: 0, itemCategories: ['Category'], itemTotalAmount: 1, itemTaxAmount: 0, itemTaxRate: 0,
+  }],
+  attachments: [{
+    ftype: 'pdf', filename: 'invoice.pdf', fileDescriptor: 'Invoice',
+    furl: 'https://example.com/invoice.pdf', fContent: 'base64',
+  }],
+  additionalData: { key: 'value' },
+}
+```
+
+#### Customer creation for pay and auth
+
+Pay and auth sessions reject missing or null customer data with `customerData is required for pay and auth sessions`.
+The payment API must match the customer through the paypoint identifiers.
+If it cannot match the customer, it returns HTTP 400 unless `forceCustomerCreation: true` allows creation.
+The optional top-level `forceCustomerCreation` flag defaults to `false` and applies only to `pay` and `auth`.
+For `tokenize`, use `tokenization.forceCustomerCreation` instead. The API rejects the top-level flag for tokenize sessions.
+
+#### ACH session settings
+
+Set ACH restrictions and request flags in the server session:
+
+```js
+config: {
+  operation: 'pay',
+  methods: ['ach'],
+  paymentDetails: { totalAmount: 50, currency: 'USD' },
+  customerData: { firstName: 'Jane', lastName: 'Doe' },
+  forceCustomerCreation: true,
+  defaults: { achAccountType: 'checking' },
+  ach: {
+    allowedAccountTypes: ['checking'],
+    confirmAccountNumber: true,
+    confirmRoutingNumber: true,
+    validation: true,
+    sameDay: true,
+  },
+}
+```
+
+- `ach` is optional for `pay` and `tokenize`. Auth sessions reject it because ACH does not support authorization.
+- A non-empty `methods` list must include `ach`. Otherwise, the API rejects the block with `ach settings require the ach method`.
+- `allowedAccountTypes` defaults to `['checking', 'savings']`. Values must be lowercase. The list must contain at least one type without duplicates.
+- `defaults.achAccountType` is optional and must be an allowed type. With one allowed type, the form uses it without a selector.
+- The server rejects an account type outside the allowed list before any payment API call.
+
+`confirmAccountNumber` and `confirmRoutingNumber` default to `false`.
+When enabled, each UI-only confirmation field must match its original value. `change.isValid` includes these checks.
+The session contains the confirmation flags. Confirmation values never enter browser submit payloads or payment API payloads.
+The existing ACH consent text remains visible.
+
+`ach.validation` defaults to `false` and applies only to pay sessions.
+It enables the payment API's ACH validation add-on through the GetPaid query flag `achValidation`.
+It does not enable local routing-number validation, microdeposits, or Plaid. The connector can also require this add-on.
+Tokenize sessions reject `ach.validation`. Use `tokenization.achValidation` instead.
+
+`ach.sameDay` defaults to `false` and applies only to pay sessions through the GetPaid query flag `sameDayACH`.
+Tokenize sessions reject it. The payment form has no same-day control.
+The server sends these query flags only when true and only for ACH pay submissions.
+The server sends `forceCustomerCreation` only when true, for any pay method or an auth submission.
+
+#### Field visibility and requiredness
+
+Set `fields` in the server session config, not in browser options:
+
+```js
+fields: {
+  card: {
+    holderName: 'required',
+    cvv: 'optional',
+    postalCode: 'hidden',
+  },
+  ach: { holderName: 'optional' },
+  check: { holderName: 'required' },
+}
+```
+
+The `fields` block, each method block, and every entry are optional.
+Every entry defaults to `required`. Values must be lowercase `required`, `optional`, or `hidden`.
+
+- `required` preserves the existing required input and validation rules.
+- `optional` shows the input and allows an empty value. The API payload omits empty credentials instead of sending `""`.
+- Non-empty optional values use the existing format rules, including three or four digits for CVV and the postal code format.
+- `hidden` removes the input from the form, client validation, and `change.fields`. The API payload omits the credential key.
+- The server rejects a non-empty browser submit value for a hidden field. Session rules also control server validation and `change.isValid`.
+
+Card number, expiration, routing number, account number, and account type cannot be configured or hidden through `fields`.
+The API rejects unknown members. The typed `fields` block replaces `requiredFields`, with no compatibility alias.
+If a non-empty `methods` list excludes a method, the API rejects its field block with `fields.<method> requires the <method> method`.
+Check is available only for pay. Tokenize sessions use the same field rules for card and ACH. Wallets are unaffected.
+
+The playground shows a method's field controls only when that method is checked.
+It sends only non-default entries and omits empty method blocks and an empty `fields` block.
+
+#### Tokenization
+
+Create tokenization configuration on your server with `Session/init`:
+
+```js
+components: [
+  {
+    type: 'payin',
+    config: {
+      operation: 'tokenize',
+      methods: ['card', 'ach'],
+      customerData: { customerId: 123 },
+      tokenization: {
+        lifetime: 'permanent', // Required: 'temporary' or 'permanent'.
+        customerMode: 'customer', // Required: 'anonymous' or 'customer'.
+        forceCustomerCreation: false, // Optional. Defaults to false.
+        achValidation: false, // Optional. Defaults to false.
+        methodDescription: 'Saved payment method', // Optional, 1 to 255 characters.
+        methodType: 0, // Optional: 0, 1, or 2. Omit for the connector default.
+      },
+    },
+  },
+];
+```
+
+- `anonymous` mode forbids `customerData`. Omit `forceCustomerCreation` or set it to `false`.
+- `customer` mode requires non-null `customerData`. The API must resolve the customer, or `forceCustomerCreation: true` must create it.
+- `temporary` methods expire after 12 hours. Use `permanent` for storage without that expiration.
+- `achValidation: true` requires ACH in `methods` and enables the API validation add-on. The connector can also require this add-on.
+- `methodType` values are `0` for single use, `1` for a universal token, and `2` for a network token. Unsupported connector types return an error. The API stores `methodDescription` unchanged.
+
+`methods` accepts only `card` and `ach`. An empty list uses the paypoint's methods, filtered to card and ACH.
+Session creation fails if no supported method remains. Wallet and check tokenization are not available.
+Fallback authorization is not offered because the API ignores `fallbackAuth` and `fallbackAuthAmount`.
+
+`tokenization` is required for `tokenize` and rejected for `pay` or `auth`.
+Omit `paymentDetails`, `invoiceData`, and `saveIfSuccess` for tokenize sessions.
+The component shows no payment total. Its default submit label is `Save`, unless `appearance.labels.submit` overrides it.
+
+#### Idempotency key
+
+`idempotencyKey` is optional in `components[].config`. Supply it from your server, or omit it for a key generated by platform-api.
+A supplied key must contain 1 to 64 characters from `[A-Za-z0-9._:-]`. The API stores it as `{sessionId}:{key}`.
+
+### Browser options
+
+`options` contains only the following browser presentation settings:
+
+```ts
+{
+  showSubmitButton?: boolean;
+  initialMethod?: 'card' | 'ach' | 'check';
+  methodOrder?: ('card' | 'ach' | 'check')[];
+}
+```
+
+`showSubmitButton: true` shows the internal submit button. Set it to `false` when the host calls `submit()`.
+
+`initialMethod` and `methodOrder` are optional browser `options`, alongside `showSubmitButton`.
+Both accept only `card`, `ach`, and `check`. `methodOrder` must be an array.
+The exported `FORM_METHODS` tuple defines the default order.
+
+1. Use only session-allowed form methods. Options never enable a method.
+2. Keep allowed `methodOrder` entries in the given order. The first occurrence wins. Ignore duplicates and disallowed entries.
+3. Append unlisted allowed methods in the default order: card, ach, check.
+4. Select `initialMethod` when session-allowed. Otherwise, select the first method in the effective order.
+5. Keep wallets in their own section. These options do not affect wallets.
+
+Without overrides, the default order and initial method stay unchanged.
+The options schema rejects unknown method names and non-array orders. It accepts duplicates for the iframe to ignore.
+The SDK forwards options unchanged through `CONFIG_SET.options`. React uses the existing `options` prop, with no new props.
+`payin.update({ options: { initialMethod: 'card', methodOrder: ['card', 'ach'] } })` remounts the iframe.
+No new session is required. Layout, density, label style, and color scheme are unchanged.
+
+### Appearance
+
+`appearance` is client-side. `update()` remounts the iframe without creating a new session.
+
+| Setting             | Values and behavior                                                                                          |
+| ------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `layout`            | `tabs`, `accordion`, `stacked`, `minimal`. Default is `tabs`. A single-method session renders the bare form. |
+| `layoutVariant`     | Density: `compact`, `standard`, `wide`.                                                                      |
+| `labelStyle`        | `above`, `floating`, `outlined`. Default is `above`.                                                         |
+| `colorScheme`       | `light`, `dark`, `system`. `system` follows the buyer's device.                                              |
+| `tokens` / `labels` | String records for supported CSS custom properties and text overrides.                                       |
+
+`above` places labels over inputs. `floating` lifts labels inside the box. `outlined` lifts labels onto a notch in the border.
+Supported tokens include `--primary`, `--background`, `--pb-container-padding`, and `--pb-container-background`.
+
+The SDK matches the iframe's `color-scheme` to its document. A mismatch makes the cross-origin frame opaque.
+Use `--pb-container-background: transparent` to show the host page through the frame in both modes.
+
+#### Text overrides
+
+Set field text in `appearance.labels`. These browser settings do not change payloads, validation, or session-allowed methods.
+
+| Label key                        | Placeholder key                           |
+| -------------------------------- | ----------------------------------------- |
+| `label.card.holderName`          | `placeholder.card.holderName`             |
+| `label.card.number`              | `placeholder.card.number`                 |
+| `label.card.expiration`          | `placeholder.card.expiration`             |
+| `label.card.cvv`                 | `placeholder.card.cvv`                    |
+| `label.card.postalCode`          | `placeholder.card.postalCode`             |
+| `label.ach.holderName`           | `placeholder.ach.holderName`              |
+| `label.ach.accountType`          | None                                      |
+| `label.ach.routingNumber`        | `placeholder.ach.routingNumber`           |
+| `label.ach.accountNumber`        | `placeholder.ach.accountNumber`           |
+| `label.ach.confirmRoutingNumber` | `placeholder.ach.confirmRoutingNumber`    |
+| `label.ach.confirmAccountNumber` | `placeholder.ach.confirmAccountNumber`    |
+| `label.check.holderName`         | `placeholder.check.holderName`            |
+| `label.check.capture`            | None, sets the RDC capture call to action |
+
+`method-check` sets the check tab label. The existing keys remain available:
+
+```text
+submit
+method-card
+method-ach
+method-applepay
+method-googlepay
+wallet-divider
+ach-consent
+error-declined
+error-generic
+```
+
+The iframe drops keys outside this allowlist. It trims values and limits them to 120 characters.
+It renders values as text with React escaping, never as HTML.
+The shared wire schema remains `Record<string, string>` because other components use different keys.
+Use the exported `PAYIN_LABEL_KEYS` tuple and `PayInLabelKey` type from `@payabli/component-contracts` for PayIn-specific typing:
+
+```ts
+import type { PayInLabelKey } from '@payabli/component-contracts';
+
+const labels: Partial<Record<PayInLabelKey, string>> = {
+  'label.card.number': 'Card number',
+  'placeholder.card.number': 'Enter card number',
+  'method-check': 'Scan a check',
+};
+
+const payin = payabli.create('payin', {
+  appearance: { labels },
+  options: {
+    initialMethod: 'ach',
+    methodOrder: ['ach', 'card', 'check'],
+  },
+});
+```
+
+### Events
+
+#### Success and errors
+
+`success` and React's `onSuccess` report confirmed success only. `submit()` resolves with the same result data.
+`PayInSuccessPayload.transactionId` identifies a pay or auth transaction when present.
+The wire success data remains an open record. The SDK preserves fields it does not interpret.
+
+For tokenize sessions, `SUBMIT_RESULT.data`, the `success` event, and the `submit()` result contain:
+
+```ts
+{ referenceId: string, customerId?: number, methodReferenceId?: string }
+```
+
+`referenceId` is the saved payment method ID, not a transaction ID. `PayInSuccessPayload` declares it as an optional string.
+
+A failed `SUBMIT_RESULT` rejects `submit()` and emits `error`, mapped to React's `onError`.
+Errors have `{ code, message, recoverable, details? }`. The SDK forwards the code and message unchanged.
+Wallet helpers report success only when the server classifies the result as successful.
+The iframe emits failed `SUBMIT_RESULT` and `ERROR` with the same error once per wallet failure.
+Recoverable failures release the lock. Non-recoverable failures keep it locked.
+
+| Code                      | Meaning and action                                                                                          |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `SUBMIT_FAILED`           | Confirmed decline or validation failure. Keep entered values and allow correction when `recoverable: true`. |
+| `OUTCOME_UNKNOWN`         | The API did not confirm the result. A prior attempt may have processed. Do not retry this session.          |
+| `SESSION_COMPLETED`       | The session already succeeded. Create a new session.                                                        |
+| `UNSUPPORTED_OPERATION`   | The session operation does not support this method. No payment API call occurs.                             |
+| `UNSUPPORTED_SAVE_METHOD` | Check cannot use `saveIfSuccess: true`. No payment API call occurs.                                         |
+
+The server can report submit codes beyond the SDK's exported `ErrorCodes` constants, including `SUBMIT_FAILED` and `UNSUPPORTED_SAVE_METHOD`.
+
+#### Lifecycle and wallet cancellation
+
+`WALLET_CANCEL` maps to the SDK event `walletCancel` and the React callback `onWalletCancel`.
+The payload is `{ wallet: 'applepay' | 'googlepay' }`.
+The iframe emits it when the buyer closes the Apple Pay sheet or Google Pay returns `statusCode: "CANCELED"`.
+Cancellation is not an error or a submit result. The iframe releases its lock, so the buyer can try another payment method.
+The SDK does not emit `error` or `success`, or settle a pending `submit()` promise, for this event.
+The `message` event also reports the inbound `WALLET_CANCEL` for the playground log.
+
+```ts
+payin.on('walletCancel', ({ wallet }) => {
+  // Update the checkout UI for the canceled wallet.
+});
+```
+
+```tsx
+<PayIn
+  onWalletCancel={({ wallet }) => {
+    // Update the checkout UI for the canceled wallet.
+  }}
+/>
+```
+
+`ready` and `rendered` are lifecycle events. Validity is `change.isValid` (`STATE_CHANGE`).
+In React, read `isValid` from `onChange`. Do not use `onReady` or `onRendered` as a validity signal.
+
+#### SDK and session errors
+
+| Code                     | Meaning and recovery                                                                                      |
+| ------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `LOAD_TIMEOUT`           | The iframe did not send READY within the timeout. The SDK retries loading once before reporting an error. |
+| `PROTOCOL_ERROR`         | postMessage validation failed.                                                                            |
+| `INVALID_STATE`          | The operation targets a destroyed instance.                                                               |
+| `SESSION_EXPIRED`        | The session reached its ceiling or refresh failed without recovery. Supply a new session.                 |
+| `SESSION_REFRESH_FAILED` | An individual auto-refresh attempt failed and is recoverable.                                             |
+| `TOKEN_EXPIRED`          | An iframe API call used an expired JWT. The SDK refreshes immediately without a public event.             |
+| `RENDER_TOKEN_EXPIRED`   | The frame URL no longer renders. The SDK rebuilds the frame and reports an error after the rebuild limit. |
+| `RENDER_TOKEN_INVALID`   | Render token signature, audience, or format checks failed. Global `sessionError` requires a new session.  |
+
+### Post-success lock and session replacement
+
+The API namespaces a partner key as `{sessionId}:{key}` so two sessions can reuse the same partner key. A generated key uses the same form: `{sessionId}:{GUID}`, 65 characters in total. Attempt 1 sends the stored value returned by bootstrap, and later attempts append `-{n}` to that value.
+The attempt counter advances only after a confirmed failure. Browser submissions do not supply the key or the attempt number.
+
+`OUTCOME_UNKNOWN` means the payment API did not confirm the outcome. A previous attempt may have been processed.
+This error is terminal for the session (`recoverable: false`). The component keeps entered values but stays locked.
+The host must not retry with this session. A fresh session is required.
+The SDK never retries a submit automatically. `SUBMIT_FAILED` remains the code for confirmed failures.
+
+After success, the component clears sensitive payment fields and locks all fields and wallet buttons.
+Repeated submissions return `SESSION_COMPLETED` with `recoverable: false`.
+Both error codes pass unchanged to the `submit()` rejection and the `error` event, or React's `onError` callback.
+
+Call `payabli.updateSession(newSession)` with a newly created session to unlock the component.
+This sends `SESSION_UPDATE` with `replace: true`. A token refresh with `replace: false` does not unlock it.
+
+Wallet sheets and form submission share one in-flight lock. Closing a wallet sheet releases it.
+After success, the iframe clears card number, CVV, expiration, account number, routing number, and check capture.
+The server records session completion and rejects later submissions before any payment API call.
+A new bootstrap session ID also remounts the form with fresh state and the new session key.
+Appearance updates and token refreshes do not clear the server completion lock.
+
+The server stores attempt counters and completion records in Redis for the session lifetime. If Redis is unavailable, submission fails closed.
+GetPaid and Authorize cache each idempotency key for two minutes before processing, regardless of the result.
+Duplicate keys return HTTP 409 without replaying the original result. HTTP 409 maps to `OUTCOME_UNKNOWN`, not a decline.
+Network failures, timeouts after dispatch, and unconfirmed server failures also map to `OUTCOME_UNKNOWN`.
+TokenStorage does not deduplicate this header. The session attempt and completion locks still apply to tokenization.
+
+### Method × operation matrix
+
+| method    | pay (GetPaid) | auth (Authorize) | tokenize (TokenStorage) |
+| --------- | ------------- | ---------------- | ----------------------- |
+| card      | yes           | yes              | yes                     |
+| ach       | yes           | NO               | yes                     |
+| check     | yes           | NO               | NO                      |
+| applepay  | yes           | yes              | NO                      |
+| googlepay | yes           | yes              | NO                      |
+
+`Session/init` rejects method and operation pairs outside this table.
+For `auth`, an empty `methods` list uses paypoint capabilities filtered to card, Apple Pay, and Google Pay.
+Session creation fails if no supported method remains.
+The iframe also rejects unsupported pairs before an API call. It never substitutes `pay` for `auth` or `tokenize`.
+`UNSUPPORTED_OPERATION` means: "The session operation does not support this payment method."
+
+### Migration from the legacy embedded component
+
+This is a pre-production breaking change. Remove obsolete configuration instead of adding compatibility aliases.
+
+| Legacy option or behavior                                     | New location or action                                                                          |
+| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Browser `operation`, `methods`, `acceptedCardBrands`          | Server `components[].config` in `Session/init`.                                                 |
+| `amount: { amount, currency }`                                | `config.paymentDetails: { totalAmount, currency }`. The total already includes the fee.         |
+| `billingAddress`                                              | Removed. Supply customer billing fields in server-owned `config.customerData`.                  |
+| `requiredFields`                                              | Removed. Use typed `config.fields` entries.                                                     |
+| PayIn `prefill`                                               | Removed from SDK options and React props. Supply customer data in the server session.           |
+| Customer, invoice, and save-on-success data in browser config | `config.customerData`, `config.invoiceData`, `config.saveIfSuccess`.                            |
+| Form selection and order                                      | Browser `options.initialMethod` and `options.methodOrder`. Only session-allowed methods appear. |
+| Field label and placeholder text                              | Browser `appearance.labels` using the keys above.                                               |
+| `appearance.mode`                                             | `appearance.colorScheme`.                                                                       |
+| Ready-means-valid behavior                                    | Use `change.isValid` or React `onChange`. `ready` and `rendered` are lifecycle events.          |
+| Repeated submit after success                                 | Create a new session and call `payabli.updateSession(newSession)`.                              |
+
+Pay and auth examples must supply non-null `customerData`. Use identifiers that match the paypoint's customer rules.
+An empty object passes session validation but does not guarantee that the payment API can resolve a customer.
+Do not send customer or invoice data from buyer-controlled browser configuration.
+
+### Rollout order
+
+1. Deploy platform-api so `Session/init` accepts and returns the new PayIn config. The bootstrap must carry that config.
+2. Publish `@payabli/component-contracts`, the `@payabli/components-web` CDN script, and `@payabli/components-react`. The SDK must support `WALLET_CANCEL`, the new error codes, and the `initialMethod` and `methodOrder` options.
+3. Deploy payabli/app with session-owned submission, field rules, tokenization, wallet classification, and locks. Remove its temporary local contract shims in a follow-up.
+4. Update playground and example installations to use those releases.
+
+Publish the SDK before deploying the iframe because an old SDK turns an unknown `WALLET_CANCEL` event into `PROTOCOL_ERROR`.
+
+The follow-up removes these temporary local contract shims:
+
+- Error literals in `app/modules/embed/payin-errors.ts`.
+- The local `WALLET_CANCEL` schema and options extension in `meta.ts`.
+- The `zod-v4` alias.
+
+### Deferred items
+
+| Area             | Not included in this contract                                                                                               |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Payment flows    | Saved-method selection, recurring payments, cloud devices, and lightbox.                                                    |
+| GetPaid metadata | Top-level `orderId`, `orderDescription`, and configurable `source`. Nested `paymentDetails` order fields remain supported.  |
+| Tokenization     | Wallet and check tokenization. Wallet storage needs a product decision about the API's hidden $0.01 authorization and void. |
+| Styling          | External CSS and per-field layout. Use supported appearance tokens, layouts, and text keys.                                 |
+
+Fallback authorization is not offered. The API ignores `fallbackAuth` and `fallbackAuthAmount`.
+Anonymous wallet storage also has an unresolved server failure. Do not bypass the wallet tokenization restriction.
+
 ## Versioning
 
 Pre-1.0. A breaking wire change is a minor bump. `MESSAGE_VERSION` changes

package/dist/errors.d.ts

@@ -2,6 +2,12 @@ export declare const ErrorCodes: {
     readonly LOAD_TIMEOUT: "LOAD_TIMEOUT";
     readonly PROTOCOL_ERROR: "PROTOCOL_ERROR";
     readonly INVALID_STATE: "INVALID_STATE";
+    /** The session operation does not support this payment method. */
+    readonly UNSUPPORTED_OPERATION: "UNSUPPORTED_OPERATION";
+    /** The payment API did not confirm the outcome. Do not retry with this session. */
+    readonly OUTCOME_UNKNOWN: "OUTCOME_UNKNOWN";
+    /** This session already completed an operation. Create a new session. */
+    readonly SESSION_COMPLETED: "SESSION_COMPLETED";
     readonly SESSION_EXPIRED: "SESSION_EXPIRED";
     readonly SESSION_REFRESH_FAILED: "SESSION_REFRESH_FAILED";
     /** Reported by an iframe whose call was rejected for an expired JWT. Triggers a refresh. */

package/dist/index.js

@@ -1678,13 +1678,49 @@ function getComponentDescriptor(type) {
  * PayIn-specific on purpose — a payout component defines its own methods in
  * its own folder.
  */
+const FORM_METHODS = ['card', 'ach', 'check'];
 const PAYMENT_METHODS = [
-    'card',
-    'ach',
-    'check',
+    ...FORM_METHODS,
     'applepay',
     'googlepay',
 ];
+/** PayIn text keys. The iframe drops other keys, trims values, and limits text to 120 characters. */
+const PAYIN_LABEL_KEYS = [
+    'submit',
+    'method-card',
+    'method-ach',
+    'method-applepay',
+    'method-googlepay',
+    'wallet-divider',
+    'ach-consent',
+    'error-declined',
+    'error-generic',
+    'method-check',
+    'label.card.holderName',
+    'placeholder.card.holderName',
+    'label.card.number',
+    'placeholder.card.number',
+    'label.card.expiration',
+    'placeholder.card.expiration',
+    'label.card.cvv',
+    'placeholder.card.cvv',
+    'label.card.postalCode',
+    'placeholder.card.postalCode',
+    'label.ach.holderName',
+    'placeholder.ach.holderName',
+    'label.ach.accountType',
+    'label.ach.routingNumber',
+    'placeholder.ach.routingNumber',
+    'label.ach.accountNumber',
+    'placeholder.ach.accountNumber',
+    'label.ach.confirmRoutingNumber',
+    'placeholder.ach.confirmRoutingNumber',
+    'label.ach.confirmAccountNumber',
+    'placeholder.ach.confirmAccountNumber',
+    'label.check.holderName',
+    'placeholder.check.holderName',
+    'label.check.capture',
+];
 /**
  * A card network. Not a payment method. Accepted brands are session config
  * (`Session/init` acceptedCardBrands), not a client option: the API owns them
@@ -1699,14 +1735,23 @@ const CARD_BRANDS = [
     'Diners',
 ];
 /**
- * Client-side UI behavior only. Business configuration — operation, methods,
- * amount, required fields, billing address — belongs to `Session/init` on the
- * partner's server, and its types belong to the API's generated SDK.
+ * Client-side UI behavior only. The partner server sets operation, methods,
+ * required fields, paymentDetails, customerData, invoiceData, and saveIfSuccess
+ * through `Session/init`. The API's generated SDK owns session types.
+ *
+ * totalAmount already includes serviceFee. Currency accepts USD or CAD.
+ * Omitted currency displays as USD and stays omitted in the API request.
+ * Customer and invoice data pass through unchanged and stay omitted when absent.
+ * saveIfSuccess defaults to false and supports card, ACH, and wallets.
  *
  * The SDK sends this in CONFIG_SET.options and payhub parses with this same
  * object (via the descriptor's `optionsSchema`).
  */
 const payinOptionsSchema = object({
+    initialMethod: optional(_enum(FORM_METHODS)
+        .check(describe('Select this form method first when session-allowed. Otherwise, use the first method in the effective order. Wallets stay separate.'))),
+    methodOrder: optional(array(_enum(FORM_METHODS))
+        .check(describe('Order session-allowed form methods only. Ignore disallowed entries and duplicates after the first occurrence. Append unlisted allowed methods in card, ach, check order. Wallets stay separate.'))),
     showSubmitButton: optional(boolean()
         .check(describe('Render the submit button inside the component. Set false when the host page owns the button and calls submit().'))),
 });
@@ -1717,6 +1762,11 @@ const payinEvents = {
         applepay: boolean(),
         googlepay: boolean(),
     }),
+    /**
+     * Emitted when the buyer closes the wallet sheet. This is not an error.
+     * The component is ready for another attempt.
+     */
+    WALLET_CANCEL: object({ wallet: _enum(['applepay', 'googlepay']) }),
     CARD_BRAND_CHANGE: object({
         /** A known brand, or 'unknown' while the number is too short to classify. */
         brand: _enum([...CARD_BRANDS, 'unknown']),
@@ -1738,6 +1788,10 @@ const payInEventSchemas = {
         event: 'walletAvailable',
         schema: payinEvents.WALLET_AVAILABLE,
     },
+    WALLET_CANCEL: {
+        event: 'walletCancel',
+        schema: payinEvents.WALLET_CANCEL,
+    },
     CARD_BRAND_CHANGE: {
         event: 'cardBrandChange',
         schema: payinEvents.CARD_BRAND_CHANGE,
@@ -1763,6 +1817,12 @@ const ErrorCodes = {
     LOAD_TIMEOUT: 'LOAD_TIMEOUT',
     PROTOCOL_ERROR: 'PROTOCOL_ERROR',
     INVALID_STATE: 'INVALID_STATE',
+    /** The session operation does not support this payment method. */
+    UNSUPPORTED_OPERATION: 'UNSUPPORTED_OPERATION',
+    /** The payment API did not confirm the outcome. Do not retry with this session. */
+    OUTCOME_UNKNOWN: 'OUTCOME_UNKNOWN',
+    /** This session already completed an operation. Create a new session. */
+    SESSION_COMPLETED: 'SESSION_COMPLETED',
     SESSION_EXPIRED: 'SESSION_EXPIRED',
     SESSION_REFRESH_FAILED: 'SESSION_REFRESH_FAILED',
     /** Reported by an iframe whose call was rejected for an expired JWT. Triggers a refresh. */
@@ -1797,4 +1857,4 @@ const BASE_COMPONENT_EVENT_NAMES = [
     'resize',
 ];
 
-export { BASE_COMPONENT_EVENT_NAMES, CARD_BRANDS, ErrorCodes, MESSAGE_SOURCE, MESSAGE_VERSION, PAYMENT_METHODS, appearanceSchema, baseInboundEvents, componentDescriptors, componentErrorSchema, componentTypes, eventEnvelopeSchema, getComponentDescriptor, outboundMessages, parseEnvelope, parseMessage, parsePayload, payInDescriptor, payInEventSchemas, payinEvents, payinOptionsSchema, register };
+export { BASE_COMPONENT_EVENT_NAMES, CARD_BRANDS, ErrorCodes, FORM_METHODS, MESSAGE_SOURCE, MESSAGE_VERSION, PAYIN_LABEL_KEYS, PAYMENT_METHODS, appearanceSchema, baseInboundEvents, componentDescriptors, componentErrorSchema, componentTypes, eventEnvelopeSchema, getComponentDescriptor, outboundMessages, parseEnvelope, parseMessage, parsePayload, payInDescriptor, payInEventSchemas, payinEvents, payinOptionsSchema, register };

package/dist/payin/definition.d.ts

@@ -45,6 +45,15 @@ export declare const payInEventSchemas: {
             googlepay: import("zod/v4/mini").ZodMiniBoolean<boolean>;
         }, import("zod/v4/core").$strip>;
     };
+    WALLET_CANCEL: {
+        event: "walletCancel";
+        schema: import("zod/v4/mini").ZodMiniObject<{
+            wallet: import("zod/v4/mini").ZodMiniEnum<{
+                applepay: "applepay";
+                googlepay: "googlepay";
+            }>;
+        }, import("zod/v4/core").$strip>;
+    };
     CARD_BRAND_CHANGE: {
         event: "cardBrandChange";
         schema: import("zod/v4/mini").ZodMiniObject<{

package/dist/payin/schema.d.ts

@@ -4,8 +4,12 @@ import * as z from 'zod/v4/mini';
  * PayIn-specific on purpose — a payout component defines its own methods in
  * its own folder.
  */
+export declare const FORM_METHODS: readonly ["card", "ach", "check"];
 export declare const PAYMENT_METHODS: readonly ["card", "ach", "check", "applepay", "googlepay"];
 export type PaymentMethodName = (typeof PAYMENT_METHODS)[number];
+/** PayIn text keys. The iframe drops other keys, trims values, and limits text to 120 characters. */
+export declare const PAYIN_LABEL_KEYS: readonly ["submit", "method-card", "method-ach", "method-applepay", "method-googlepay", "wallet-divider", "ach-consent", "error-declined", "error-generic", "method-check", "label.card.holderName", "placeholder.card.holderName", "label.card.number", "placeholder.card.number", "label.card.expiration", "placeholder.card.expiration", "label.card.cvv", "placeholder.card.cvv", "label.card.postalCode", "placeholder.card.postalCode", "label.ach.holderName", "placeholder.ach.holderName", "label.ach.accountType", "label.ach.routingNumber", "placeholder.ach.routingNumber", "label.ach.accountNumber", "placeholder.ach.accountNumber", "label.ach.confirmRoutingNumber", "placeholder.ach.confirmRoutingNumber", "label.ach.confirmAccountNumber", "placeholder.ach.confirmAccountNumber", "label.check.holderName", "placeholder.check.holderName", "label.check.capture"];
+export type PayInLabelKey = (typeof PAYIN_LABEL_KEYS)[number];
 /**
  * A card network. Not a payment method. Accepted brands are session config
  * (`Session/init` acceptedCardBrands), not a client option: the API owns them
@@ -14,14 +18,29 @@ export type PaymentMethodName = (typeof PAYMENT_METHODS)[number];
 export declare const CARD_BRANDS: readonly ["Visa", "Mastercard", "Amex", "Discover", "Jcb", "Diners"];
 export type CardBrand = (typeof CARD_BRANDS)[number];
 /**
- * Client-side UI behavior only. Business configuration — operation, methods,
- * amount, required fields, billing address — belongs to `Session/init` on the
- * partner's server, and its types belong to the API's generated SDK.
+ * Client-side UI behavior only. The partner server sets operation, methods,
+ * required fields, paymentDetails, customerData, invoiceData, and saveIfSuccess
+ * through `Session/init`. The API's generated SDK owns session types.
+ *
+ * totalAmount already includes serviceFee. Currency accepts USD or CAD.
+ * Omitted currency displays as USD and stays omitted in the API request.
+ * Customer and invoice data pass through unchanged and stay omitted when absent.
+ * saveIfSuccess defaults to false and supports card, ACH, and wallets.
  *
  * The SDK sends this in CONFIG_SET.options and payhub parses with this same
  * object (via the descriptor's `optionsSchema`).
  */
 export declare const payinOptionsSchema: z.ZodMiniObject<{
+    initialMethod: z.ZodMiniOptional<z.ZodMiniEnum<{
+        card: "card";
+        ach: "ach";
+        check: "check";
+    }>>;
+    methodOrder: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniEnum<{
+        card: "card";
+        ach: "ach";
+        check: "check";
+    }>>>;
     showSubmitButton: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
 }, z.core.$strip>;
 /** PayIn's own inbound events, beyond the base set every component shares. */
@@ -39,6 +58,16 @@ export declare const payinEvents: {
         applepay: z.ZodMiniBoolean<boolean>;
         googlepay: z.ZodMiniBoolean<boolean>;
     }, z.core.$strip>;
+    /**
+     * Emitted when the buyer closes the wallet sheet. This is not an error.
+     * The component is ready for another attempt.
+     */
+    readonly WALLET_CANCEL: z.ZodMiniObject<{
+        wallet: z.ZodMiniEnum<{
+            applepay: "applepay";
+            googlepay: "googlepay";
+        }>;
+    }, z.core.$strip>;
     readonly CARD_BRAND_CHANGE: z.ZodMiniObject<{
         brand: z.ZodMiniEnum<{
             unknown: "unknown";
@@ -68,5 +97,8 @@ export declare const payinEvents: {
  * fields the SDK does not interpret, and it forwards all of them.
  */
 export type PayInSuccessPayload = {
+    /** The transaction ID for pay or auth sessions. */
     transactionId?: string;
+    /** The saved payment method ID for tokenize sessions. */
+    referenceId?: string;
 } & Record<string, unknown>;

package/dist/sdk.d.ts

@@ -29,7 +29,7 @@ export interface PayabliConfig {
 export interface CreateOptions<T extends ComponentType = ComponentType> {
     appearance?: AppearanceOptions;
     options?: ComponentOptions<T>;
-    prefill?: Record<string, string>;
+    prefill?: T extends 'payin' ? never : Record<string, string>;
     locale?: string;
     timeout?: number;
 }

package/package.json

@@ -1,14 +1,9 @@
 {
   "name": "@payabli/component-contracts",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Wire schemas, component registry, and partner-facing types shared by the Payabli embedded components SDK and payhub.",
   "private": false,
-  "license": "UNLICENSED",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/payabli/components-web.git",
-    "directory": "packages/component-contracts"
-  },
+  "license": "MIT",
   "type": "module",
   "sideEffects": false,
   "main": "dist/index.js",
@@ -23,7 +18,8 @@
   },
   "files": [
     "dist",
-    "!dist/__tests__"
+    "!dist/__tests__",
+    "LICENSE.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -34,6 +30,7 @@
   "devDependencies": {
     "tslib": "^2.8.1"
   },
+  "homepage": "https://docs.payabli.com/guides/pay-in-components-overview",
   "scripts": {
     "generate": "node scripts/generate-registry.mjs",
     "build": "pnpm generate && rm -rf dist && rollup -c && tsc -p tsconfig.build.json --emitDeclarationOnly",