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.
- package/CHANGELOG.md +26 -0
- package/README.md +125 -720
- package/dist/index.d.ts +6 -2
- package/dist/index.js +9 -1
- package/dist/iskubixi.d.ts +3 -1
- package/dist/iskubixi.js +165 -16
- package/dist/providers/payment-provider.d.ts +17 -0
- package/dist/providers/paypal-payment-provider.d.ts +41 -0
- package/dist/providers/paypal-payment-provider.js +457 -0
- package/dist/providers/provider-http.d.ts +15 -0
- package/dist/providers/provider-http.js +140 -0
- package/dist/providers/stripe-payment-provider.d.ts +43 -0
- package/dist/providers/stripe-payment-provider.js +339 -0
- package/dist/providers/waafipay-payment-provider.d.ts +1 -0
- package/dist/providers/waafipay-payment-provider.js +4 -0
- package/dist/types/configuration.d.ts +3 -1
- package/dist/types/payment.d.ts +7 -1
- package/dist/types/provider-capabilities.d.ts +2 -1
- package/docs/api-reference.md +93 -0
- package/docs/architecture.md +25 -0
- package/docs/authentication.md +36 -0
- package/docs/biometric-adapters.md +44 -107
- package/docs/configuration.md +57 -0
- package/docs/contributing.md +30 -0
- package/docs/custom-providers.md +50 -0
- package/docs/errors.md +35 -0
- package/docs/examples.md +46 -0
- package/docs/getting-started.md +64 -0
- package/docs/idempotency.md +26 -0
- package/docs/index.md +56 -0
- package/docs/installation.md +28 -0
- package/docs/javascript.md +22 -0
- package/docs/limitations.md +31 -0
- package/docs/passkeys.md +38 -0
- package/docs/payment-authorization.md +33 -141
- package/docs/payment-lifecycle.md +34 -0
- package/docs/payment-verification.md +18 -0
- package/docs/payments.md +68 -0
- package/docs/provider-development.md +33 -0
- package/docs/providers.md +123 -0
- package/docs/qr-payments.md +42 -0
- package/docs/refunds.md +20 -0
- package/docs/security.md +37 -0
- package/docs/storage.md +36 -0
- package/docs/testing.md +24 -0
- package/docs/troubleshooting.md +28 -0
- package/docs/typescript.md +25 -0
- package/docs/webhook-security.md +22 -0
- package/docs/webhooks.md +59 -0
- package/examples/javascript/payment-authorization.js +1 -0
- package/examples/typescript/payment-providers.ts +83 -0
- package/package.json +18 -2
|
@@ -1,157 +1,49 @@
|
|
|
1
|
-
# Payment authorization
|
|
1
|
+
# Payment authorization
|
|
2
2
|
|
|
3
|
-
Payment authorization
|
|
4
|
-
|
|
5
|
-
provider has transferred money.
|
|
3
|
+
Payment authorization binds a short-lived authentication event to an exact
|
|
4
|
+
payment request.
|
|
6
5
|
|
|
7
|
-
|
|
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
|
|
34
|
-
userId:
|
|
9
|
+
const authorization = await sdk.lacag.ogolaanshoAbuur({
|
|
10
|
+
userId: "user-123",
|
|
11
|
+
hab: "waji",
|
|
35
12
|
lacag: {
|
|
36
|
-
qadarka:
|
|
37
|
-
lacagta:
|
|
38
|
-
bixiye: "
|
|
39
|
-
tixraac:
|
|
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
|
-
|
|
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
|
|
53
|
-
userId:
|
|
54
|
-
authorizationId:
|
|
55
|
-
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
|
-
|
|
65
|
-
|
|
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
|
-
|
|
100
|
-
protected. Do not store or transmit raw biometric images, templates, or
|
|
101
|
-
measurements.
|
|
38
|
+
## Check authorization
|
|
102
39
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
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
|
-
|
|
145
|
-
|
|
146
|
-
|
|
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.
|
package/docs/payments.md
ADDED
|
@@ -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.
|
package/docs/refunds.md
ADDED
|
@@ -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.
|
package/docs/security.md
ADDED
|
@@ -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.
|
package/docs/storage.md
ADDED
|
@@ -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.
|
package/docs/testing.md
ADDED
|
@@ -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.
|