@fire-spark/payments-paymentez-checkout 0.0.0-stage → 0.18.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.
@@ -0,0 +1,173 @@
1
+ import { PaymentAdapter, PaymentContext, PaymentMetadata, PaymentPolicy, PaymentResult } from "@fire-spark/payments";
2
+ //#region src/types.d.ts
3
+ /** Answer of the Spark Paymentez `status` operation (no keys, no PAN). */
4
+ type PaymentezOutcome = {
5
+ status: "PAID" | "FAILED" | "PENDING";
6
+ transaction_id: string | null;
7
+ dev_reference: string | null;
8
+ status_detail: number | null;
9
+ authorization_code: string | null;
10
+ amount: number | null;
11
+ card_brand: string | null;
12
+ card_type: string | null;
13
+ last4: string | null;
14
+ message: string | null;
15
+ error_code: string | null;
16
+ };
17
+ /** `prepare` answer: the Payment Checkout reference of this attempt. */
18
+ type PaymentezPrepared = {
19
+ reference: string;
20
+ checkout_url: string | null;
21
+ };
22
+ /** `PaymentCheckout.modal` `env_mode` of the payment environment. */
23
+ type PaymentezEnvMode = "stg" | "prod";
24
+ type PaymentezCheckoutInput = {
25
+ /** `paymentCheckout.open({ reference })`. */
26
+ reference: string;
27
+ envMode: PaymentezEnvMode;
28
+ attemptReference: string;
29
+ /** Aborted on timeout or cancel: `close()` the checkout, resolve `closed`. */
30
+ signal: AbortSignal;
31
+ };
32
+ /** `onResponse` payload: `{ transaction: { status, id, status_detail } }`. */
33
+ type PaymentezCheckoutResponse = {
34
+ transaction?: {
35
+ status?: string;
36
+ id?: string;
37
+ status_detail?: number;
38
+ };
39
+ error?: {
40
+ type?: string;
41
+ help?: string;
42
+ description?: string;
43
+ };
44
+ };
45
+ /** How the checkout ended. */
46
+ type PaymentezCheckoutOutcome =
47
+ /** `onResponse` fired (success or failure): Spark confirms it. */
48
+ {
49
+ type: "response";
50
+ response: PaymentezCheckoutResponse;
51
+ } |
52
+ /** `onClose` without a response, or `close()` after the signal. */
53
+ {
54
+ type: "closed";
55
+ by: "user" | "system";
56
+ };
57
+ /**
58
+ * Implemented once per template with the Paymentez Payment Checkout
59
+ * (`payment_checkout_3.0.0.min.js`). On the web open it from the pay
60
+ * button click (browsers block popups otherwise); on React Native run it
61
+ * inside a WebView served over https.
62
+ */
63
+ type PaymentezCheckoutBridge = {
64
+ open(input: PaymentezCheckoutInput): Promise<PaymentezCheckoutOutcome>;
65
+ };
66
+ //#endregion
67
+ //#region src/checkout.d.ts
68
+ type PaymentezCheckoutOptions = {
69
+ /** Opens the Paymentez Payment Checkout with the reference. */
70
+ bridge: PaymentezCheckoutBridge;
71
+ language?: "es" | "en";
72
+ /** Customer email when the order has none (Paymentez requires one). */
73
+ email?: string;
74
+ };
75
+ /**
76
+ * Paymentez (Nuvei LATAM) card through its Payment Checkout. Spark creates
77
+ * the reference with the server application (`prepare`), the template opens
78
+ * the checkout (`bridge`), and Spark reads the transaction it answered
79
+ * (`status`): PAID only for this attempt and amount. The webhook confirms a
80
+ * charge the channel never reported. A paid charge is refunded by Spark
81
+ * with the order cancel or refund (whole transaction).
82
+ */
83
+ declare const paymentezCheckoutPayments: (options: PaymentezCheckoutOptions) => PaymentAdapter;
84
+ //#endregion
85
+ //#region src/constants.d.ts
86
+ declare const PAYMENTEZ_PROVIDER = "paymentez";
87
+ /**
88
+ * The checkout covers the bank OTP or 3DS challenge. One automatic attempt:
89
+ * a retry is a new reference and a new charge.
90
+ */
91
+ declare const PAYMENTEZ_CHECKOUT_POLICY: Partial<PaymentPolicy>;
92
+ /** `ctx.storage` key with the transaction id the checkout answered. */
93
+ declare const transactionKey: (attemptReference: string) => string;
94
+ //#endregion
95
+ //#region src/errors.d.ts
96
+ /**
97
+ * Paymentez `status_detail` codes of a failed card transaction (see the
98
+ * ficha table). Unknown codes fall back to `CARD_DECLINED`.
99
+ */
100
+ declare const paymentezErrors: Readonly<Record<string, import("@fire-spark/payments").PaymentErrorEntry>> & {
101
+ "6": {
102
+ code: "FRAUD_SUSPECTED";
103
+ source: string;
104
+ };
105
+ "9": {
106
+ code: "CARD_DECLINED";
107
+ source: string;
108
+ };
109
+ "10": {
110
+ code: "PROVIDER_UNAVAILABLE";
111
+ source: string;
112
+ };
113
+ "11": {
114
+ code: "FRAUD_SUSPECTED";
115
+ source: string;
116
+ };
117
+ "12": {
118
+ code: "FRAUD_SUSPECTED";
119
+ source: string;
120
+ };
121
+ "13": {
122
+ code: "WALLET_EXPIRED";
123
+ source: string;
124
+ };
125
+ "14": {
126
+ code: "WALLET_EXPIRED";
127
+ source: string;
128
+ };
129
+ "15": {
130
+ code: "WALLET_EXPIRED";
131
+ source: string;
132
+ };
133
+ "16": {
134
+ code: "CARD_DECLINED";
135
+ source: string;
136
+ };
137
+ "17": {
138
+ code: "CANCELLED_BY_USER";
139
+ source: string;
140
+ };
141
+ "18": {
142
+ code: "CANCELLED_BY_USER";
143
+ source: string;
144
+ };
145
+ "19": {
146
+ code: "CARD_DECLINED";
147
+ source: string;
148
+ };
149
+ "20": {
150
+ code: "WALLET_EXPIRED";
151
+ source: string;
152
+ };
153
+ "33": {
154
+ code: "CARD_DECLINED";
155
+ source: string;
156
+ };
157
+ "37": {
158
+ code: "CARD_DECLINED";
159
+ source: string;
160
+ };
161
+ "47": {
162
+ code: "INVALID_REQUEST";
163
+ source: string;
164
+ };
165
+ };
166
+ //#endregion
167
+ //#region src/result.d.ts
168
+ /** Ids and card data of a Paymentez outcome; nothing sensitive. */
169
+ declare const paymentezMetadataOf: (ctx: PaymentContext, outcome: PaymentezOutcome) => PaymentMetadata;
170
+ /** PAID / FAILED / PENDING result of a Paymentez outcome. */
171
+ declare const paymentezResultOf: (ctx: PaymentContext, outcome: PaymentezOutcome) => PaymentResult;
172
+ //#endregion
173
+ export { PAYMENTEZ_CHECKOUT_POLICY, PAYMENTEZ_PROVIDER, type PaymentezCheckoutBridge, type PaymentezCheckoutInput, PaymentezCheckoutOptions, type PaymentezCheckoutOutcome, type PaymentezCheckoutResponse, type PaymentezEnvMode, type PaymentezOutcome, type PaymentezPrepared, paymentezCheckoutPayments, paymentezErrors, paymentezMetadataOf, paymentezResultOf, transactionKey };
package/dist/index.js ADDED
@@ -0,0 +1,305 @@
1
+ import { PaymentError, createPaymentError, definePaymentErrors, toPaymentError } from "@fire-spark/payments";
2
+ //#region src/constants.ts
3
+ const PAYMENTEZ_PROVIDER = "paymentez";
4
+ /**
5
+ * The checkout covers the bank OTP or 3DS challenge. One automatic attempt:
6
+ * a retry is a new reference and a new charge.
7
+ */
8
+ const PAYMENTEZ_CHECKOUT_POLICY = {
9
+ timeout_ms: 9e5,
10
+ max_attempts: 1
11
+ };
12
+ /** `ctx.storage` key with the transaction id the checkout answered. */
13
+ const transactionKey = (attemptReference) => {
14
+ return `paymentez:transaction:${attemptReference}`;
15
+ };
16
+ //#endregion
17
+ //#region src/errors.ts
18
+ const source = "docs/payments/paymentez/checkout.md#11-errores";
19
+ /**
20
+ * Paymentez `status_detail` codes of a failed card transaction (see the
21
+ * ficha table). Unknown codes fall back to `CARD_DECLINED`.
22
+ */
23
+ const paymentezErrors = definePaymentErrors({
24
+ "6": {
25
+ code: "FRAUD_SUSPECTED",
26
+ source
27
+ },
28
+ "9": {
29
+ code: "CARD_DECLINED",
30
+ source
31
+ },
32
+ "10": {
33
+ code: "PROVIDER_UNAVAILABLE",
34
+ source
35
+ },
36
+ "11": {
37
+ code: "FRAUD_SUSPECTED",
38
+ source
39
+ },
40
+ "12": {
41
+ code: "FRAUD_SUSPECTED",
42
+ source
43
+ },
44
+ "13": {
45
+ code: "WALLET_EXPIRED",
46
+ source
47
+ },
48
+ "14": {
49
+ code: "WALLET_EXPIRED",
50
+ source
51
+ },
52
+ "15": {
53
+ code: "WALLET_EXPIRED",
54
+ source
55
+ },
56
+ "16": {
57
+ code: "CARD_DECLINED",
58
+ source
59
+ },
60
+ "17": {
61
+ code: "CANCELLED_BY_USER",
62
+ source
63
+ },
64
+ "18": {
65
+ code: "CANCELLED_BY_USER",
66
+ source
67
+ },
68
+ "19": {
69
+ code: "CARD_DECLINED",
70
+ source
71
+ },
72
+ "20": {
73
+ code: "WALLET_EXPIRED",
74
+ source
75
+ },
76
+ "33": {
77
+ code: "CARD_DECLINED",
78
+ source
79
+ },
80
+ "37": {
81
+ code: "CARD_DECLINED",
82
+ source
83
+ },
84
+ "47": {
85
+ code: "INVALID_REQUEST",
86
+ source
87
+ }
88
+ });
89
+ //#endregion
90
+ //#region src/result.ts
91
+ /** Paymentez card type codes (`vi`, `mc`, `ax`, `di`, `dc`…). */
92
+ const BRANDS = {
93
+ vi: "Visa",
94
+ mc: "Mastercard",
95
+ ax: "American Express",
96
+ di: "Diners",
97
+ dc: "Discover",
98
+ ms: "Maestro"
99
+ };
100
+ const brandOf = (value) => {
101
+ if (!value) return null;
102
+ return BRANDS[value.toLowerCase()] ?? value;
103
+ };
104
+ /** Ids and card data of a Paymentez outcome; nothing sensitive. */
105
+ const paymentezMetadataOf = (ctx, outcome) => {
106
+ const reference = outcome.authorization_code ?? outcome.transaction_id;
107
+ const p1 = { provider_transaction_id: outcome.transaction_id };
108
+ const p2 = {
109
+ authorization_code: outcome.authorization_code,
110
+ reference
111
+ };
112
+ const p3 = {
113
+ brand: brandOf(outcome.card_brand),
114
+ last4: outcome.last4
115
+ };
116
+ const payment = {
117
+ ...p1,
118
+ ...p2,
119
+ ...p3
120
+ };
121
+ const provider = {
122
+ transaction_id: outcome.transaction_id,
123
+ status_detail: outcome.status_detail
124
+ };
125
+ return {
126
+ attempt_reference: ctx.attemptReference,
127
+ payment,
128
+ provider
129
+ };
130
+ };
131
+ const cardDetailsOf = (outcome) => {
132
+ const brand = brandOf(outcome.card_brand);
133
+ if (!brand || !outcome.last4) return null;
134
+ const auth = outcome.authorization_code;
135
+ const base = {
136
+ method: "CARD",
137
+ brand,
138
+ last4: outcome.last4
139
+ };
140
+ return auth ? {
141
+ ...base,
142
+ auth_code: auth
143
+ } : base;
144
+ };
145
+ const failedResult = (ctx, error, metadata) => {
146
+ const base = metadata ?? { attempt_reference: ctx.attemptReference };
147
+ const review = error.code === "AMBIGUOUS" ? { needs_review: true } : {};
148
+ const m = {
149
+ ...base,
150
+ ...review,
151
+ error
152
+ };
153
+ return {
154
+ status: "FAILED",
155
+ amount: ctx.amount.value,
156
+ metadata: m,
157
+ error
158
+ };
159
+ };
160
+ /** PAID / FAILED / PENDING result of a Paymentez outcome. */
161
+ const paymentezResultOf = (ctx, outcome) => {
162
+ const metadata = paymentezMetadataOf(ctx, outcome);
163
+ const amount = ctx.amount.value;
164
+ if (outcome.status === "PAID") return {
165
+ status: "PAID",
166
+ amount,
167
+ metadata,
168
+ details: cardDetailsOf(outcome)
169
+ };
170
+ if (outcome.status === "PENDING") return {
171
+ status: "PENDING",
172
+ amount,
173
+ metadata
174
+ };
175
+ const raw = {
176
+ code: outcome.status_detail ?? outcome.error_code,
177
+ message: outcome.message,
178
+ attempt: ctx.attempt,
179
+ fallback: "CARD_DECLINED"
180
+ };
181
+ return failedResult(ctx, toPaymentError(paymentezErrors, raw), metadata);
182
+ };
183
+ /** Spark operation failures: a missing answer may still have charged. */
184
+ const serverErrorOf = (ctx, cause) => {
185
+ const e = cause;
186
+ const extra = {
187
+ provider_message: e?.message ?? "Paymentez request failed",
188
+ attempt: ctx.attempt
189
+ };
190
+ if (e?.code === "AMBIGUOUS" || e?.status === 504) return createPaymentError("AMBIGUOUS", extra);
191
+ if (e?.status === 409) return createPaymentError("INVALID_CREDENTIALS", extra);
192
+ if (e?.status === 400) return createPaymentError("INVALID_REQUEST", extra);
193
+ return createPaymentError("PROVIDER_UNAVAILABLE", extra);
194
+ };
195
+ //#endregion
196
+ //#region src/checkout.ts
197
+ const envModeOf = (ctx) => {
198
+ return ctx.environment === "production" ? "prod" : "stg";
199
+ };
200
+ const record = (value) => {
201
+ if (!value || typeof value !== "object") return {};
202
+ return value;
203
+ };
204
+ /**
205
+ * Paymentez (Nuvei LATAM) card through its Payment Checkout. Spark creates
206
+ * the reference with the server application (`prepare`), the template opens
207
+ * the checkout (`bridge`), and Spark reads the transaction it answered
208
+ * (`status`): PAID only for this attempt and amount. The webhook confirms a
209
+ * charge the channel never reported. A paid charge is refunded by Spark
210
+ * with the order cancel or refund (whole transaction).
211
+ */
212
+ const paymentezCheckoutPayments = (options) => {
213
+ const { bridge } = options;
214
+ const confirm = async (ctx, transactionId) => {
215
+ ctx.ui.message({
216
+ text: "Confirmando pago…",
217
+ kind: "waiting"
218
+ });
219
+ const input = { transaction_id: transactionId };
220
+ return paymentezResultOf(ctx, await ctx.server.call("status", input));
221
+ };
222
+ const pending = (ctx) => {
223
+ const metadata = { attempt_reference: ctx.attemptReference };
224
+ return {
225
+ status: "PENDING",
226
+ amount: ctx.amount.value,
227
+ metadata
228
+ };
229
+ };
230
+ const start = async (ctx) => {
231
+ try {
232
+ const input = {
233
+ locale: options.language ?? "es",
234
+ ...options.email ? { email: options.email } : {}
235
+ };
236
+ const prepared = await ctx.server.call("prepare", input);
237
+ if (!prepared.reference) return failedResult(ctx, createPaymentError("PROVIDER_UNAVAILABLE", {
238
+ provider_message: "Paymentez returned no reference",
239
+ attempt: ctx.attempt
240
+ }));
241
+ const b1 = {
242
+ reference: prepared.reference,
243
+ envMode: envModeOf(ctx)
244
+ };
245
+ const b2 = {
246
+ attemptReference: ctx.attemptReference,
247
+ signal: ctx.signal
248
+ };
249
+ const outcome = await bridge.open({
250
+ ...b1,
251
+ ...b2
252
+ });
253
+ if (outcome.type === "closed") {
254
+ if (outcome.by === "system") return pending(ctx);
255
+ return failedResult(ctx, createPaymentError("CANCELLED_BY_USER", { attempt: ctx.attempt }));
256
+ }
257
+ const transaction = record(outcome.response.transaction);
258
+ const id = typeof transaction.id === "string" ? transaction.id : null;
259
+ if (!id) return failedResult(ctx, createPaymentError("CARD_DECLINED", {
260
+ provider_message: outcome.response.error?.description ?? "Paymentez checkout failed",
261
+ attempt: ctx.attempt
262
+ }));
263
+ await ctx.storage.set(transactionKey(ctx.attemptReference), id);
264
+ return await confirm(ctx, id);
265
+ } catch (cause) {
266
+ if (cause instanceof PaymentError) return failedResult(ctx, cause.error);
267
+ return failedResult(ctx, serverErrorOf(ctx, cause));
268
+ }
269
+ };
270
+ /** A pending charge (OTP, 3DS, unread answer) read again from Spark. */
271
+ const query = async (ctx, result) => {
272
+ if (result.status !== "PENDING") return result;
273
+ const fromResult = record(result.metadata.provider).transaction_id;
274
+ const stored = await ctx.storage.get(transactionKey(ctx.attemptReference));
275
+ const id = typeof fromResult === "string" ? fromResult : stored;
276
+ if (!id) return result;
277
+ try {
278
+ return await confirm(ctx, id);
279
+ } catch (cause) {
280
+ return failedResult(ctx, serverErrorOf(ctx, cause));
281
+ }
282
+ };
283
+ /** Nothing was charged: the reference is left to expire. */
284
+ const cancel = async (_ctx, result) => {
285
+ return {
286
+ ...result,
287
+ status: "CANCELLED"
288
+ };
289
+ };
290
+ const reversalFor = (result) => {
291
+ return result.status === "PAID" ? "server" : "cancel";
292
+ };
293
+ return {
294
+ provider: PAYMENTEZ_PROVIDER,
295
+ method: "CARD",
296
+ errors: paymentezErrors,
297
+ policy: PAYMENTEZ_CHECKOUT_POLICY,
298
+ start,
299
+ query,
300
+ cancel,
301
+ reversalFor
302
+ };
303
+ };
304
+ //#endregion
305
+ export { PAYMENTEZ_CHECKOUT_POLICY, PAYMENTEZ_PROVIDER, paymentezCheckoutPayments, paymentezErrors, paymentezMetadataOf, paymentezResultOf, transactionKey };
package/package.json CHANGED
@@ -1,6 +1,59 @@
1
1
  {
2
2
  "name": "@fire-spark/payments-paymentez-checkout",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.18.0",
4
+ "description": "Fire Spark Paymentez (Nuvei LATAM) adapter: card payments through the Paymentez Payment Checkout (web, and React Native through a WebView)",
5
+ "type": "module",
6
+ "sideEffects": false,
7
+ "files": [
8
+ "dist"
9
+ ],
10
+ "main": "./dist/index.js",
11
+ "types": "./dist/index.d.ts",
12
+ "exports": {
13
+ ".": {
14
+ "types": "./dist/index.d.ts",
15
+ "import": "./dist/index.js",
16
+ "default": "./dist/index.js"
17
+ }
18
+ },
19
+ "dependencies": {
20
+ "@fire-spark/types": "^0.18.0",
21
+ "@fire-spark/payments": "^0.18.0"
22
+ },
23
+ "devDependencies": {
24
+ "tsdown": "^0.22.14",
25
+ "typescript": "^7.0.2",
26
+ "vitest": "^2.1.8"
27
+ },
28
+ "publishConfig": {
29
+ "access": "public"
30
+ },
31
+ "tsdown": {
32
+ "entry": [
33
+ "src/index.ts"
34
+ ],
35
+ "format": [
36
+ "esm"
37
+ ],
38
+ "platform": "neutral",
39
+ "dts": {
40
+ "tsconfig": "tsconfig.build.json"
41
+ },
42
+ "clean": true,
43
+ "deps": {
44
+ "neverBundle": [
45
+ "@fire-spark/payments",
46
+ "@fire-spark/types"
47
+ ]
48
+ }
49
+ },
50
+ "scripts": {
51
+ "build": "tsdown",
52
+ "dev": "tsdown --watch",
53
+ "check-types": "tsc --noEmit",
54
+ "test:utils": "vitest run",
55
+ "lint": "oxlint ./src --max-warnings=0",
56
+ "format": "oxfmt ./src",
57
+ "check-format": "oxfmt --check ./src"
58
+ }
6
59
  }
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.