iskubixi 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +125 -720
  3. package/dist/index.d.ts +6 -2
  4. package/dist/index.js +9 -1
  5. package/dist/iskubixi.d.ts +3 -1
  6. package/dist/iskubixi.js +165 -16
  7. package/dist/providers/payment-provider.d.ts +17 -0
  8. package/dist/providers/paypal-payment-provider.d.ts +41 -0
  9. package/dist/providers/paypal-payment-provider.js +457 -0
  10. package/dist/providers/provider-http.d.ts +15 -0
  11. package/dist/providers/provider-http.js +140 -0
  12. package/dist/providers/stripe-payment-provider.d.ts +43 -0
  13. package/dist/providers/stripe-payment-provider.js +339 -0
  14. package/dist/providers/waafipay-payment-provider.d.ts +1 -0
  15. package/dist/providers/waafipay-payment-provider.js +4 -0
  16. package/dist/types/configuration.d.ts +3 -1
  17. package/dist/types/payment.d.ts +7 -1
  18. package/dist/types/provider-capabilities.d.ts +2 -1
  19. package/docs/api-reference.md +93 -0
  20. package/docs/architecture.md +25 -0
  21. package/docs/authentication.md +36 -0
  22. package/docs/biometric-adapters.md +44 -107
  23. package/docs/configuration.md +57 -0
  24. package/docs/contributing.md +30 -0
  25. package/docs/custom-providers.md +50 -0
  26. package/docs/errors.md +35 -0
  27. package/docs/examples.md +46 -0
  28. package/docs/getting-started.md +64 -0
  29. package/docs/idempotency.md +26 -0
  30. package/docs/index.md +56 -0
  31. package/docs/installation.md +28 -0
  32. package/docs/javascript.md +22 -0
  33. package/docs/limitations.md +31 -0
  34. package/docs/passkeys.md +38 -0
  35. package/docs/payment-authorization.md +33 -141
  36. package/docs/payment-lifecycle.md +34 -0
  37. package/docs/payment-verification.md +18 -0
  38. package/docs/payments.md +68 -0
  39. package/docs/provider-development.md +33 -0
  40. package/docs/providers.md +123 -0
  41. package/docs/qr-payments.md +42 -0
  42. package/docs/refunds.md +20 -0
  43. package/docs/security.md +37 -0
  44. package/docs/storage.md +36 -0
  45. package/docs/testing.md +24 -0
  46. package/docs/troubleshooting.md +28 -0
  47. package/docs/typescript.md +25 -0
  48. package/docs/webhook-security.md +22 -0
  49. package/docs/webhooks.md +59 -0
  50. package/examples/javascript/payment-authorization.js +1 -0
  51. package/examples/typescript/payment-providers.ts +83 -0
  52. package/package.json +18 -2
@@ -1,157 +1,49 @@
1
- # Payment authorization integration
1
+ # Payment authorization
2
2
 
3
- Payment authorization asks a customer to approve one immutable payment request
4
- with a supported, trusted authentication adapter. It does not confirm that a
5
- provider has transferred money.
3
+ Payment authorization binds a short-lived authentication event to an exact
4
+ payment request.
6
5
 
7
- IskuBixi is a server-side npm SDK, not a hosted payment service. Your
8
- application owns its users, sessions, database, provider credentials, browser
9
- application, recovery process, and deployment.
10
-
11
- ## Lifecycle
12
-
13
- 1. The application backend authenticates the customer and loads the intended
14
- order from trusted application data.
15
- 2. The backend calls `iskubixi.lacag.ogolaanshoAbuur()` with the authenticated
16
- user ID, exact payment details, and requested authentication method.
17
- 3. IskuBixi saves the payment details, computes a binding digest, creates an
18
- authentication session, and returns an authorization ID, expiry,
19
- client-safe authentication options, and safe payment summary.
20
- 4. The frontend shows the returned summary and performs the ceremony supported
21
- by the configured adapter.
22
- 5. The frontend sends the authorization ID and response to the application
23
- backend. It does not supply replacement payment details.
24
- 6. The backend obtains the user ID from its authenticated session and calls
25
- `iskubixi.lacag.ogolaanshoXaqiiji()`.
26
- 7. IskuBixi verifies the bound challenge and consumes the authorization once,
27
- then starts the stored payment request. An uncertain provider result moves
28
- to `reconciliation_required`; it is not retried automatically.
29
- 8. The application checks provider verification or processes a verified
30
- provider webhook before marking an order paid or fulfilling it.
6
+ ## Create authorization
31
7
 
32
8
  ```ts
33
- const authorization = await iskubixi.lacag.ogolaanshoAbuur({
34
- userId: authenticatedSession.user.id,
9
+ const authorization = await sdk.lacag.ogolaanshoAbuur({
10
+ userId: "user-123",
11
+ hab: "waji",
35
12
  lacag: {
36
- qadarka: order.total,
37
- lacagta: order.currency,
38
- bixiye: "edahab",
39
- tixraac: order.reference
40
- },
41
- hab: "waji"
13
+ qadarka: 25,
14
+ lacagta: "USD",
15
+ bixiye: "stripe",
16
+ tixraac: "ORDER-1001"
17
+ }
42
18
  });
43
-
44
- // Send authorization to your own frontend. Never accept userId or payment
45
- // details from the browser as the trusted source.
46
- return authorization;
47
19
  ```
48
20
 
49
- After the frontend returns its authentication response:
21
+ The result contains `authorizationId`, expiry, client-safe authentication
22
+ options, and a payment summary. The payment is not created until verification
23
+ succeeds.
24
+
25
+ ## Verify authorization
50
26
 
51
27
  ```ts
52
- const result = await iskubixi.lacag.ogolaanshoXaqiiji({
53
- userId: authenticatedSession.user.id,
54
- authorizationId: request.body.authorizationId,
55
- response: request.body.response
28
+ const result = await sdk.lacag.ogolaanshoXaqiiji({
29
+ userId: "user-123",
30
+ authorizationId: authorization.authorizationId,
31
+ response: adapterResponse
56
32
  });
57
-
58
- if (result.xaalad === "processing") {
59
- // Authentication passed and the saved request was submitted.
60
- // result.payment.xaalad is a separate payment status, often "sugaya".
61
- }
62
33
  ```
63
34
 
64
- These public methods are `ogolaanshoAbuur`,
65
- `ogolaanshoXaqiiji`, and `ogolaanshoXaalad`. The final verification request
66
- accepts no amount, currency, provider, or merchant reference. The SDK retrieves
67
- all payment details from the authorization record.
68
-
69
- ## Authentication requirements
70
-
71
- Configure an application-owned `AmaanoodLaqabsade` that supports the requested
72
- method and declares `supportsPaymentAuthorization: true`. It must bind the
73
- payment digest into its challenge and verify the same digest, user, method,
74
- expiry, and user-verification response. The adapter must prove the requested
75
- modality; generic WebAuthn user verification does not identify face,
76
- fingerprint, iris, palm, or PIN use. An ordinary passkey adapter that cannot
77
- prove the requested method will be rejected for payment authorization.
78
-
79
- The frontend runs the adapter's ceremony. It must not be trusted to assert which
80
- modality succeeded. Use HTTPS for WebAuthn, configure the exact RP ID and
81
- allowed origins in a WebAuthn adapter, and provide a non-biometric recovery
82
- process for unsupported devices or cancelled prompts.
83
-
84
- ## State and durability
85
-
86
- Authorization states (`pending`, `verifying`, `authorized`, `failed`,
87
- `expired`, `processing`, `reconciliation_required`) are separate from payment
88
- states (`sugaya`, `guuleystay`, `fashilmay`, and others). Authentication
89
- success is never payment success.
90
-
91
- The built-in in-memory authorization and authentication-session stores are for
92
- tests and local development only. They are lost on restart and do not provide
93
- atomic coordination across instances. Production deployments must supply
94
- application-owned durable stores implementing `PaymentAuthorizationStore` and
95
- `AmaanoodAuthenticationSessionStore`, with atomic unique creation, claim,
96
- transition, and consume operations shared by all workers. Use appropriate
97
- durable stores for payment transactions and idempotency as well.
35
+ The SDK atomically rejects replay, wrong user, changed request data, expiry,
36
+ and provider uncertainty. It creates the provider payment once on success.
98
37
 
99
- Keep authorization IDs, stored payment details, and session references
100
- protected. Do not store or transmit raw biometric images, templates, or
101
- measurements.
38
+ ## Check authorization
102
39
 
103
- ## Provider idempotency and uncertain outcomes
104
-
105
- The SDK's local idempotency record does not make a remote provider call
106
- idempotent. A provider adapter may declare `capabilities.paymentIdempotency`
107
- only when the provider documents the semantics. IskuBixi then forwards a stable
108
- key derived from the authorization ID.
109
-
110
- If a provider call times out, fails ambiguously, or the SDK cannot save the
111
- returned payment ID, the authorization is marked
112
- `reconciliation_required`. The SDK does not retry and does not allow another
113
- payment attempt from that authorization. An interrupted worker can leave a
114
- record in `processing`; treat it as uncertain. Reconcile through documented
115
- provider tools, provider lookup, or authenticated webhook evidence before
116
- deciding what to do. Database transitions and external provider calls cannot be
117
- one atomic transaction.
118
-
119
- The bundled WaafiPay provider adapter is sandbox-focused and does not claim
120
- documented provider-side idempotency, lookup, or transaction verification.
121
- Do not infer those capabilities. Use only provider operations established by
122
- the provider's current documentation.
123
-
124
- ## Webhook and payment confirmation
125
-
126
- Use an authenticated webhook adapter for the provider's signed callbacks.
127
- Validate the raw request body and provider signature, apply verified events
128
- through the SDK webhook API, and maintain your own order/payment state.
129
- Alternatively, use provider lookup/verification only if your adapter
130
- implements and documents it. Do not fulfill an order merely because the
131
- authorization result is `processing` or because passkey verification
132
- succeeded.
133
-
134
- ## Errors and fallback
135
-
136
- Handle unsupported authentication methods, invalid/expired/replayed responses,
137
- wrong-user requests, storage errors, provider failures, and
138
- `reconciliation_required` explicitly. A cancelled browser ceremony should not
139
- be treated as success. Do not retry an uncertain payment by creating a new
140
- authorization until the previous outcome has been reconciled.
141
-
142
- ## Production checklist
40
+ ```ts
41
+ const status = await sdk.lacag.ogolaanshoXaalad({
42
+ userId: "user-123",
43
+ authorizationId: authorization.authorizationId
44
+ });
45
+ ```
143
46
 
144
- - [ ] Derive `userId` from the server's authenticated session.
145
- - [ ] Load payment amount, currency, provider, and reference from trusted
146
- application data.
147
- - [ ] Use durable stores with atomic operations across all workers.
148
- - [ ] Use a trusted adapter that verifies the exact requested method and
149
- user-verification result.
150
- - [ ] For WebAuthn, validate origin/RP ID and require UV; do not claim a
151
- specific modality without documented evidence.
152
- - [ ] Keep provider secrets on the backend, protected by a secret manager.
153
- - [ ] Process only authenticated provider lookup results or signed webhooks as
154
- payment confirmation.
155
- - [ ] Reconcile uncertain outcomes before any further payment attempt.
156
- - [ ] Offer recovery for unsupported authenticators and account/device loss.
157
- - [ ] Never collect, log, or store raw biometric data.
47
+ The authorization binds the user, amount, currency, provider, and reference.
48
+ Authentication or customer approval is not itself proof of payment; provider
49
+ confirmation or a verified webhook establishes success.
@@ -0,0 +1,34 @@
1
+ # Payment lifecycle
2
+
3
+ ```text
4
+ Application
5
+ -> IskuBixi.lacag.samee
6
+ -> selected provider adapter
7
+ -> provider transaction ID
8
+ -> local transaction record
9
+
10
+ Provider response / webhook
11
+ -> status validation
12
+ -> exact amount/currency/reference match
13
+ -> trusted success/pending/failure state
14
+ ```
15
+
16
+ Creation may produce pending, failed, or provider-handoff state. It is never
17
+ unconditional success.
18
+
19
+ The SDK supports:
20
+
21
+ - provider-side idempotency keys when advertised;
22
+ - SDK idempotency fingerprints;
23
+ - concurrency coalescing;
24
+ - expiry;
25
+ - status lookup;
26
+ - verification;
27
+ - confirmation/capture;
28
+ - cancellation where supported;
29
+ - refunds;
30
+ - refund status lookup;
31
+ - verified webhooks.
32
+
33
+ After a network timeout, reconcile with the provider rather than blindly
34
+ retrying a write.
@@ -0,0 +1,18 @@
1
+ # Payment verification and status
2
+
3
+ Use provider lookup or verification for server-side truth.
4
+
5
+ ```ts
6
+ const status = await sdk.lacag.xaalad({ lacagId: paymentId });
7
+ const verification = await sdk.lacag.cadee({ lacagId: paymentId });
8
+ ```
9
+
10
+ `lacag.cadee()` returns provider verification metadata with `waaJiraa: true`
11
+ and requires an adapter with payment-verification support.
12
+
13
+ The SDK validates the provider response against the originally stored amount,
14
+ currency, reference, and payment ID. A changed or malformed response is rejected.
15
+
16
+ For Stripe, verify a PaymentIntent after checkout. For PayPal, verify that the
17
+ order capture is completed. Never mark an order successful because a redirect,
18
+ approval page, or authentication ceremony was reached.
@@ -0,0 +1,68 @@
1
+ # Payments
2
+
3
+ ## Create
4
+
5
+ ```ts
6
+ const payment = await sdk.lacag.samee({
7
+ qadarka: 25,
8
+ lacagta: "USD",
9
+ bixiye: "stripe",
10
+ tixraac: "ORDER-1001",
11
+ lambarka: "252611111111",
12
+ furahaIdempotency: "order-1001-create",
13
+ dhacayaa: "2026-12-01T12:00:00Z"
14
+ });
15
+ ```
16
+
17
+ Fields:
18
+
19
+ - `qadarka`: positive, finite number.
20
+ - `lacagta`: provider/currency validation; pass an uppercase three-letter code.
21
+ - `bixiye`: provider identifier.
22
+ - `tixraac`: application reference.
23
+ - `lambarka`: optional account/wallet number for providers that support it.
24
+ - `furahaIdempotency`: optional SDK/provider idempotency key.
25
+ - `dhacayaa`: optional ISO 8601 payment expiry.
26
+
27
+ ## Confirm/capture
28
+
29
+ ```ts
30
+ const confirmed = await sdk.lacag.qabso({
31
+ lacagId: payment.id,
32
+ furahaIdempotency: "order-1001-confirm"
33
+ });
34
+ ```
35
+
36
+ Only providers declaring `paymentConfirmation` support this operation. Stripe
37
+ supports server-side confirmation; PayPal supports capture.
38
+
39
+ ## Status
40
+
41
+ ```ts
42
+ const status = await sdk.lacag.xaalad({ lacagId: payment.id });
43
+ ```
44
+
45
+ Statuses: `sugaya` pending, `guuleystay` successful, `fashilmay` failed,
46
+ `joojiyay` cancelled, `dhacay` expired, `laCeliyay` refunded.
47
+
48
+ Provider details can include `providerStatus` and `nextAction`.
49
+
50
+ ## Verification
51
+
52
+ ```ts
53
+ const result = await sdk.lacag.cadee({ lacagId: payment.id });
54
+ ```
55
+
56
+ Verification is only trusted when the provider adapter reports an exact stored
57
+ payment match. It does not accept arbitrary frontend-reported success.
58
+
59
+ ## List
60
+
61
+ ```ts
62
+ const page = await sdk.lacag.liiska({
63
+ bixiye: "stripe",
64
+ xaalad: "guuleystay",
65
+ bogga: 1,
66
+ xadka: 50
67
+ });
68
+ ```
@@ -0,0 +1,33 @@
1
+ # Provider development
2
+
3
+ Implement only operations with official API support.
4
+
5
+ ## Contracts
6
+
7
+ `PaymentProviderFactory.create(credentials)` creates a `PaymentProvider`.
8
+
9
+ The provider contract includes:
10
+
11
+ - `createPayment`
12
+ - `findPayment`
13
+ - `verifyPayment`
14
+ - optional `confirmPayment`
15
+ - optional `cancelPayment`
16
+ - optional `refundPayment`
17
+ - optional `findRefundStatus`
18
+ - optional capabilities
19
+
20
+ Declare capabilities accurately. The SDK also infers backward-compatible
21
+ capabilities from implemented methods.
22
+
23
+ ## Required implementation behavior
24
+
25
+ - use only official endpoints and authentication;
26
+ - validate malformed/unexpected responses;
27
+ - validate amount, currency, reference, and status;
28
+ - configure timeout and abort behavior;
29
+ - handle network errors safely;
30
+ - forward idempotency only if the provider contract supports it;
31
+ - redact credentials from all errors and logs;
32
+ - verify webhook signatures with raw bytes;
33
+ - never claim success from request submission alone.
@@ -0,0 +1,123 @@
1
+ # Payment providers
2
+
3
+ The source of truth for provider status is the implementation and its
4
+ capability report. No integration is considered verified against an official
5
+ sandbox or live environment unless it was actually tested with credentials.
6
+
7
+ ## Status matrix
8
+
9
+ | Provider | Create | Lookup | Verify | Confirm/capture | Cancel | Refund/status | Webhooks |
10
+ |---|---|---|---|---|---|---|---|
11
+ | Stripe | Yes | Yes | Yes | Confirm/cancel | Yes | Full refund/status | Stripe raw-body signatures |
12
+ | PayPal | Order | Yes | Yes | Capture | No | Full capture refund/status | PayPal remote verification |
13
+ | WaafiPay | Sandbox purchase | No | No | No | No | No | Separate signature adapter |
14
+ | EVC | No | No | No | No | No | No | No |
15
+ | eDahab | No | No | No | No | No | No | No |
16
+ | Zaad | No | No | No | No | No | No | No |
17
+ | Banks | No | No | No | No | No | No | No |
18
+ | Simulator | Local only | Local only | Local only | Local status control | No | Local refund | No real provider webhook |
19
+
20
+ ## Stripe
21
+
22
+ The package exports `StripePaymentProviderFactory`,
23
+ `StripePaymentProvider`, and `StripeWebhookAdapter`.
24
+
25
+ ```ts
26
+ import {
27
+ IskuBixi,
28
+ StripePaymentProviderFactory,
29
+ StripeWebhookAdapter
30
+ } from "iskubixi";
31
+
32
+ const sdk = new IskuBixi({
33
+ bixiyeyaasha: {
34
+ stripe: { apiKey: process.env.STRIPE_SECRET_KEY! }
35
+ },
36
+ laqabsadayaasha: {
37
+ stripe: new StripePaymentProviderFactory({ environment: "test" })
38
+ },
39
+ laqabsadayaashaWebhook: {
40
+ stripe: new StripeWebhookAdapter({
41
+ secret: process.env.STRIPE_WEBHOOK_SECRET!
42
+ })
43
+ }
44
+ });
45
+ ```
46
+
47
+ For live use, set `environment: "live"` and use an `sk_live_` key. Test mode
48
+ requires `sk_test_`. The adapter cannot enable Stripe for an account where
49
+ Stripe does not support the merchant or business country.
50
+
51
+ ## PayPal
52
+
53
+ The package exports `PayPalPaymentProviderFactory`,
54
+ `PayPalPaymentProvider`, and `PayPalWebhookAdapter`.
55
+
56
+ ```ts
57
+ import {
58
+ IskuBixi,
59
+ PayPalPaymentProviderFactory,
60
+ PayPalWebhookAdapter
61
+ } from "iskubixi";
62
+
63
+ const credentials = {
64
+ clientId: process.env.PAYPAL_CLIENT_ID!,
65
+ clientSecret: process.env.PAYPAL_CLIENT_SECRET!
66
+ };
67
+
68
+ const sdk = new IskuBixi({
69
+ bixiyeyaasha: { paypal: credentials },
70
+ laqabsadayaasha: {
71
+ paypal: new PayPalPaymentProviderFactory({ environment: "sandbox" })
72
+ },
73
+ laqabsadayaashaWebhook: {
74
+ paypal: new PayPalWebhookAdapter(credentials, {
75
+ environment: "sandbox",
76
+ webhookId: process.env.PAYPAL_WEBHOOK_ID!
77
+ })
78
+ }
79
+ });
80
+ ```
81
+
82
+ Creating an order is not capture. The SDK returns an approval redirect when
83
+ PayPal provides one. The application must capture and verify the order through
84
+ the provider API or webhook.
85
+
86
+ ## WaafiPay
87
+
88
+ `WaafiPayPaymentProviderFactory` implements only sandbox purchase creation.
89
+ It is explicitly limited to sandbox mode. Lookup, verification, confirmation,
90
+ cancellation, refunds, and refund lookup are unsupported in the SDK.
91
+
92
+ ```ts
93
+ import {
94
+ IskuBixi,
95
+ WaafiPayPaymentProviderFactory
96
+ } from "iskubixi";
97
+
98
+ const waafi = new WaafiPayPaymentProviderFactory({
99
+ environment: "sandbox",
100
+ formatTimestamp: () => "20261122T000000Z " // Replace with provider format.
101
+ });
102
+ ```
103
+
104
+ Obtain the merchant UID, API user ID, API key, and exact timestamp format from
105
+ WaafiPay merchant documentation. The adapter validates credentials but does not
106
+ prove that a merchant account is enabled or that live charging is allowed.
107
+
108
+ ## Providers without direct adapters
109
+
110
+ The identifiers `edahab`, `evc`, `zaad`, and `bank` do not have invented API
111
+ implementations. Local simulation is available for `edahab`, `evc`, `zaad`,
112
+ and `bank` only with `allowSimulation: true`. Live-mode credentials never fall
113
+ back to simulation.
114
+
115
+ Applications can implement the public `PaymentProvider` and
116
+ `PaymentProviderFactory` contracts after they receive official API
117
+ documentation and authorized credentials.
118
+
119
+ ## Google Pay
120
+
121
+ Google Pay is a wallet/checkout technology, not a standalone provider adapter.
122
+ A processor that the SDK supports or a custom provider must implement the real
123
+ payment, merchant eligibility, capture, verification, refund, and webhook flow.
@@ -0,0 +1,42 @@
1
+ # QR payments
2
+
3
+ ## Create
4
+
5
+ ```ts
6
+ const qr = await sdk.qr.samee({
7
+ qadarka: 20,
8
+ lacagta: "USD",
9
+ bixiye: "edahab",
10
+ lambarka: "252611111111",
11
+ furahaIdempotency: "qr-order-1001",
12
+ dhacayaa: new Date(Date.now() + 15 * 60 * 1000).toISOString()
13
+ });
14
+ ```
15
+
16
+ The result includes a QR payload in `nuxur`, the QR reference, payment ID,
17
+ amount, currency, and expiry.
18
+
19
+ ## Read
20
+
21
+ ```ts
22
+ const info = await sdk.qr.akhriso({ nuxur: qr.nuxur });
23
+ ```
24
+
25
+ Reading validates the payload format, reference, expiry, and associated payment.
26
+ It does not create or fulfill another payment.
27
+
28
+ ## Validate a reference
29
+
30
+ ```ts
31
+ const valid = await sdk.qr.cadee({ tixraac: qr.tixraac });
32
+ ```
33
+
34
+ ## Status and cancellation
35
+
36
+ ```ts
37
+ const status = await sdk.qr.xaalad({ tixraac: qr.tixraac });
38
+ const cancelled = await sdk.qr.jooji({ tixraac: qr.tixraac });
39
+ ```
40
+
41
+ Cancellation requires provider cancellation support and a pending payment.
42
+ The simulator has no provider cancellation support.
@@ -0,0 +1,20 @@
1
+ # Refunds
2
+
3
+ Refund requests require a payment ID and idempotency key.
4
+
5
+ ```ts
6
+ const refund = await sdk.lacag.celi({
7
+ lacagId: payment.id,
8
+ furahaIdempotency: "order-1001-refund"
9
+ });
10
+
11
+ const refundStatus = await sdk.lacag.celintaXaalad({
12
+ celinId: refund.id
13
+ });
14
+ ```
15
+
16
+ The public refund request has no amount field. Refunds are full refunds.
17
+ Supported adapters must provide the refund and refund-status operations.
18
+
19
+ Stripe and PayPal implement full refund flows. WaafiPay does not implement
20
+ refund creation or status lookup.
@@ -0,0 +1,37 @@
1
+ # Security
2
+
3
+ ## Credentials
4
+
5
+ - Keep provider secrets in environment variables or secret management.
6
+ - Never place secrets in browser bundles or source-controlled examples.
7
+ - Never return credential objects from application endpoints.
8
+ - Never print credentials in application or SDK logs.
9
+ - Rotate credentials and signing secrets when compromised.
10
+
11
+ ## Payment truth
12
+
13
+ Never mark success solely because:
14
+
15
+ - payment creation returned successfully;
16
+ - a redirect or approval screen was shown;
17
+ - a biometric challenge was authenticated;
18
+ - a frontend reported success.
19
+
20
+ Use a provider lookup, verification, confirmation/capture, or verified webhook
21
+ that exactly matches the stored payment.
22
+
23
+ ## Webhooks
24
+
25
+ Verify raw bytes with the provider-specific adapter before parsing or applying
26
+ events. Use deduplication and exact payment-detail matching.
27
+
28
+ ## Biometrics
29
+
30
+ Do not store raw biometric samples. Use a trusted modality adapter and never
31
+ infer face, fingerprint, iris, or palm use from ordinary WebAuthn user
32
+ verification alone.
33
+
34
+ ## Authorization
35
+
36
+ Payment authorization is short-lived and bound to user, amount, currency,
37
+ provider, and reference. Authorization replay and request changes are rejected.
@@ -0,0 +1,36 @@
1
+ # Storage
2
+
3
+ All built-in stores are in-memory and therefore process-local. Use replaceable
4
+ application-owned stores for durable or horizontally scaled deployments.
5
+
6
+ ## Relevant contracts
7
+
8
+ - `PaymentIdempotencyStore`
9
+ - `RefundIdempotencyStore`
10
+ - `PaymentStateStore`
11
+ - `PaymentTransactionStore`
12
+ - `RefundStore`
13
+ - `QrPaymentStore`
14
+ - `WebhookEventStore`
15
+ - `PaymentAuthorizationStore`
16
+ - `AmaanoodChallengeStore`
17
+ - `AmaanoodCredentialStore`
18
+
19
+ Implement the corresponding exported interface, then pass it through
20
+ `IskuBixiQaabeyn`.
21
+
22
+ ```ts
23
+ const sdk = new IskuBixi({
24
+ bixiyeyaasha: { stripe: { apiKey: process.env.STRIPE_SECRET_KEY! } },
25
+ laqabsadayaasha: {
26
+ stripe: new StripePaymentProviderFactory({ environment: "test" })
27
+ },
28
+ keydkaIdempotency: applicationPaymentIdempotencyStore,
29
+ keydkaLacagaha: applicationTransactionStore,
30
+ keydkaWebhook: applicationWebhookStore
31
+ });
32
+ ```
33
+
34
+ Production storage should provide atomic operations, consistent reads, event
35
+ deduplication, and appropriate TTL/cleanup. Custom store failures are returned
36
+ through SDK storage errors without exposing store implementation details.
@@ -0,0 +1,24 @@
1
+ # Testing
2
+
3
+ Run:
4
+
5
+ ```sh
6
+ npm ci
7
+ npm test
8
+ npm audit
9
+ npm pack --dry-run
10
+ ```
11
+
12
+ ## Test levels
13
+
14
+ - **Unit tests:** SDK logic and validation.
15
+ - **Mock HTTP tests:** provider request/response behavior.
16
+ - **Contract tests:** expected provider payload and response shapes.
17
+ - **Official sandbox tests:** require authorized provider credentials.
18
+ - **Live transactions:** require explicit approval and never run by default.
19
+
20
+ Mock and unit tests establish SDK behavior, not real merchant settlement.
21
+ Do not claim official provider access without evidence.
22
+
23
+ The current suite includes security, idempotency, payment lifecycle,
24
+ verification, QR, webhook, passkey, and provider-adapter regression tests.
@@ -0,0 +1,28 @@
1
+ # Troubleshooting
2
+
3
+ ## Provider requires an adapter
4
+
5
+ Stripe and PayPal require explicit factories. EVC, eDahab, Zaad, and bank
6
+ providers require custom real adapters outside the built-in simulator.
7
+
8
+ ## Live credentials rejected
9
+
10
+ Check that Stripe test/live key prefixes match `environment`.
11
+ Check that PayPal environment is `sandbox` or `live`.
12
+ Check that WaafiPay is not configured outside sandbox support.
13
+
14
+ ## Payment remains pending
15
+
16
+ Retrieve status or verification through the provider. For PayPal, confirm that
17
+ the order was captured. For Stripe, complete the required PaymentIntent client
18
+ handoff and retrieve server-side state.
19
+
20
+ ## Webhook rejected
21
+
22
+ Use unchanged raw bytes, provider signing secrets, exact headers, and the
23
+ configured provider adapter.
24
+
25
+ ## Secrets appear in errors
26
+
27
+ This should not occur. Report the error and verify that provider/custom storage
28
+ implementations do not place credentials in thrown messages or error causes.