@fire-spark/payments-transbank-webpay 0.0.0-stage → 0.17.3

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,129 @@
1
+ import { PaymentAdapter, PaymentCardType, PaymentContext, PaymentMetadata, PaymentPolicy, PaymentResult, StandardPaymentError } from "@fire-spark/payments";
2
+ //#region src/constants.d.ts
3
+ declare const TRANSBANK_PROVIDER = "transbank";
4
+ declare const WEBPAY_METHOD = "CARD";
5
+ /** Webpay Plus charges whole pesos. */
6
+ declare const WEBPAY_CURRENCY = "CLP";
7
+ /** Label of the challenge, for the template's logs. */
8
+ declare const WEBPAY_CHALLENGE_VERSION = "WEBPAY_PLUS_1.2";
9
+ /**
10
+ * The Webpay form lives up to 10 minutes in integration (4 in
11
+ * production) and the token 5 minutes before the form opens. One
12
+ * automatic attempt: a retry is a new transaction.
13
+ */
14
+ declare const WEBPAY_POLICY: Partial<PaymentPolicy>;
15
+ //#endregion
16
+ //#region src/errors.d.ts
17
+ /**
18
+ * Webpay Plus `response_code` rejections. -1 to -5 read as level 1
19
+ * (default); a merchant with level 2 enabled (from 2021-03-01, by email to
20
+ * Transbank) gets -1 to -11 with other meanings, mapped the same way
21
+ * where they overlap.
22
+ */
23
+ declare const webpayErrors: Readonly<Record<string, import("@fire-spark/payments").PaymentErrorEntry>> & {
24
+ "-1": {
25
+ code: "INVALID_CARD";
26
+ source: string;
27
+ };
28
+ "-2": {
29
+ code: "CARD_DECLINED";
30
+ source: string;
31
+ };
32
+ "-3": {
33
+ code: "CARD_DECLINED";
34
+ source: string;
35
+ };
36
+ "-4": {
37
+ code: "CARD_DECLINED";
38
+ source: string;
39
+ };
40
+ "-5": {
41
+ code: "FRAUD_SUSPECTED";
42
+ source: string;
43
+ };
44
+ "-6": {
45
+ code: "CARD_DECLINED";
46
+ source: string;
47
+ };
48
+ "-7": {
49
+ code: "CARD_DECLINED";
50
+ source: string;
51
+ };
52
+ "-8": {
53
+ code: "EXPIRED_CARD";
54
+ source: string;
55
+ };
56
+ "-9": {
57
+ code: "CARD_DECLINED";
58
+ source: string;
59
+ };
60
+ "-10": {
61
+ code: "CARD_DECLINED";
62
+ source: string;
63
+ };
64
+ "-11": {
65
+ code: "LIMIT_EXCEEDED";
66
+ source: string;
67
+ };
68
+ };
69
+ //#endregion
70
+ //#region src/types.d.ts
71
+ /** `create` answer: post `token_ws` to `url`. */
72
+ type WebpayCreated = {
73
+ token: string;
74
+ url: string;
75
+ };
76
+ /** Why a Webpay attempt did not end `PAID`. */
77
+ type WebpayFailure = "DECLINED" | "CANCELLED" | "TIMEOUT" | "AMOUNT_MISMATCH" | "ERROR";
78
+ /** Answer of the Spark `confirm` operation (no keys, last 4 only). */
79
+ type WebpayOutcome = {
80
+ status: "PAID" | "FAILED" | "PENDING";
81
+ failure: WebpayFailure | null;
82
+ token: string | null;
83
+ webpay_status: string | null;
84
+ response_code: number | null;
85
+ buy_order: string | null;
86
+ session_id: string | null;
87
+ amount: number | null;
88
+ authorization_code: string | null;
89
+ payment_type_code: string | null;
90
+ installments_number: number | null;
91
+ installments_amount: number | null;
92
+ card_last4: string | null;
93
+ vci: string | null;
94
+ accounting_date: string | null;
95
+ transaction_date: string | null;
96
+ message: string | null;
97
+ };
98
+ //#endregion
99
+ //#region src/result.d.ts
100
+ /** `VD` debit, `VP` prepaid, every other sale type is credit. */
101
+ declare const webpayCardTypeOf: (code: string | null) => PaymentCardType | null;
102
+ /**
103
+ * Same metadata the Fire Spark return writes: `provider.token` is what
104
+ * the server refunds with.
105
+ */
106
+ declare const webpayMetadataOf: (ctx: PaymentContext, outcome: WebpayOutcome) => PaymentMetadata;
107
+ declare const failedResult: (ctx: PaymentContext, error: StandardPaymentError, metadata?: PaymentMetadata) => PaymentResult;
108
+ /** Spark error of a failed Webpay outcome. */
109
+ declare const webpayErrorOf: (ctx: PaymentContext, outcome: WebpayOutcome) => StandardPaymentError;
110
+ /** PAID / FAILED / PENDING result of a Webpay outcome. */
111
+ declare const webpayResultOf: (ctx: PaymentContext, outcome: WebpayOutcome) => PaymentResult;
112
+ /** Spark operation failures: a lost answer may still have charged. */
113
+ declare const serverErrorOf: (ctx: PaymentContext, cause: unknown) => StandardPaymentError;
114
+ //#endregion
115
+ //#region src/webpay.d.ts
116
+ /**
117
+ * Transbank Webpay Plus (Chile) for web and apps. Spark creates the
118
+ * transaction with the commerce keys (`create`); the template opens the
119
+ * Webpay form as a payment challenge (`ui.challenge`, a form `POST` of
120
+ * `token_ws`: popup or new tab on the web, WebView in an app; Transbank
121
+ * advises against an iframe); Webpay sends the customer back to the Fire
122
+ * Spark return, which commits and closes the tender; then the adapter
123
+ * reads the result with `confirm`, which also commits when the customer
124
+ * closed the form before the return arrived. A paid charge is reversed by
125
+ * Spark with the order cancel or refund.
126
+ */
127
+ declare const transbankWebpayPayments: () => PaymentAdapter;
128
+ //#endregion
129
+ export { TRANSBANK_PROVIDER, WEBPAY_CHALLENGE_VERSION, WEBPAY_CURRENCY, WEBPAY_METHOD, WEBPAY_POLICY, type WebpayCreated, type WebpayFailure, type WebpayOutcome, failedResult, serverErrorOf, transbankWebpayPayments, webpayCardTypeOf, webpayErrorOf, webpayErrors, webpayMetadataOf, webpayResultOf };
package/dist/index.js ADDED
@@ -0,0 +1,317 @@
1
+ import { createPaymentError, definePaymentErrors, toPaymentError } from "@fire-spark/payments";
2
+ //#region src/constants.ts
3
+ const TRANSBANK_PROVIDER = "transbank";
4
+ const WEBPAY_METHOD = "CARD";
5
+ /** Webpay Plus charges whole pesos. */
6
+ const WEBPAY_CURRENCY = "CLP";
7
+ /** Label of the challenge, for the template's logs. */
8
+ const WEBPAY_CHALLENGE_VERSION = "WEBPAY_PLUS_1.2";
9
+ /**
10
+ * The Webpay form lives up to 10 minutes in integration (4 in
11
+ * production) and the token 5 minutes before the form opens. One
12
+ * automatic attempt: a retry is a new transaction.
13
+ */
14
+ const WEBPAY_POLICY = {
15
+ timeout_ms: 9e5,
16
+ max_attempts: 1
17
+ };
18
+ //#endregion
19
+ //#region src/errors.ts
20
+ const source = "docs/payments/transbank/webpay.md#11-errores";
21
+ /**
22
+ * Webpay Plus `response_code` rejections. -1 to -5 read as level 1
23
+ * (default); a merchant with level 2 enabled (from 2021-03-01, by email to
24
+ * Transbank) gets -1 to -11 with other meanings, mapped the same way
25
+ * where they overlap.
26
+ */
27
+ const webpayErrors = definePaymentErrors({
28
+ "-1": {
29
+ code: "INVALID_CARD",
30
+ source
31
+ },
32
+ "-2": {
33
+ code: "CARD_DECLINED",
34
+ source
35
+ },
36
+ "-3": {
37
+ code: "CARD_DECLINED",
38
+ source
39
+ },
40
+ "-4": {
41
+ code: "CARD_DECLINED",
42
+ source
43
+ },
44
+ "-5": {
45
+ code: "FRAUD_SUSPECTED",
46
+ source
47
+ },
48
+ "-6": {
49
+ code: "CARD_DECLINED",
50
+ source
51
+ },
52
+ "-7": {
53
+ code: "CARD_DECLINED",
54
+ source
55
+ },
56
+ "-8": {
57
+ code: "EXPIRED_CARD",
58
+ source
59
+ },
60
+ "-9": {
61
+ code: "CARD_DECLINED",
62
+ source
63
+ },
64
+ "-10": {
65
+ code: "CARD_DECLINED",
66
+ source
67
+ },
68
+ "-11": {
69
+ code: "LIMIT_EXCEEDED",
70
+ source
71
+ }
72
+ });
73
+ //#endregion
74
+ //#region src/result.ts
75
+ /** `VD` debit, `VP` prepaid, every other sale type is credit. */
76
+ const webpayCardTypeOf = (code) => {
77
+ if (code === "VD") return "DEBIT";
78
+ if (code === "VP") return "PREPAID";
79
+ if (code) return "CREDIT";
80
+ return null;
81
+ };
82
+ /**
83
+ * Same metadata the Fire Spark return writes: `provider.token` is what
84
+ * the server refunds with.
85
+ */
86
+ const webpayMetadataOf = (ctx, outcome) => {
87
+ const count = outcome.installments_number ?? 0;
88
+ const installments = count > 0 ? {
89
+ count,
90
+ type: outcome.payment_type_code
91
+ } : null;
92
+ const payment = {
93
+ provider_transaction_id: outcome.token,
94
+ authorization_code: outcome.authorization_code,
95
+ reference: outcome.authorization_code ?? outcome.buy_order,
96
+ card_type: webpayCardTypeOf(outcome.payment_type_code),
97
+ brand: null,
98
+ last4: outcome.card_last4,
99
+ installments
100
+ };
101
+ const provider = {
102
+ token: outcome.token,
103
+ outcome
104
+ };
105
+ return {
106
+ attempt_reference: ctx.attemptReference,
107
+ payment,
108
+ provider
109
+ };
110
+ };
111
+ const cardDetailsOf = (outcome) => {
112
+ const last4 = outcome.card_last4;
113
+ if (!last4) return null;
114
+ const auth = outcome.authorization_code;
115
+ const count = outcome.installments_number ?? 0;
116
+ const d1 = {
117
+ method: "CARD",
118
+ brand: "Webpay",
119
+ last4
120
+ };
121
+ const d2 = auth ? { auth_code: auth } : {};
122
+ const d3 = count > 1 ? { installments: count } : {};
123
+ return {
124
+ ...d1,
125
+ ...d2,
126
+ ...d3
127
+ };
128
+ };
129
+ const failedResult = (ctx, error, metadata) => {
130
+ const base = metadata ?? { attempt_reference: ctx.attemptReference };
131
+ const review = error.code === "AMBIGUOUS" ? { needs_review: true } : {};
132
+ const m = {
133
+ ...base,
134
+ ...review,
135
+ error
136
+ };
137
+ return {
138
+ status: "FAILED",
139
+ amount: ctx.amount.value,
140
+ metadata: m,
141
+ error
142
+ };
143
+ };
144
+ /** Spark error of a failed Webpay outcome. */
145
+ const webpayErrorOf = (ctx, outcome) => {
146
+ const extra = {
147
+ provider_message: outcome.message,
148
+ attempt: ctx.attempt
149
+ };
150
+ if (outcome.failure === "CANCELLED") return createPaymentError("CANCELLED_BY_USER", extra);
151
+ if (outcome.failure === "TIMEOUT") return createPaymentError("USER_TIMEOUT", extra);
152
+ if (outcome.failure === "AMOUNT_MISMATCH") return createPaymentError("AMBIGUOUS", extra);
153
+ if (outcome.failure === "ERROR") return createPaymentError("PROVIDER_UNAVAILABLE", extra);
154
+ return toPaymentError(webpayErrors, {
155
+ code: outcome.response_code,
156
+ message: outcome.message,
157
+ attempt: ctx.attempt,
158
+ fallback: "CARD_DECLINED"
159
+ });
160
+ };
161
+ /** PAID / FAILED / PENDING result of a Webpay outcome. */
162
+ const webpayResultOf = (ctx, outcome) => {
163
+ const metadata = webpayMetadataOf(ctx, outcome);
164
+ const amount = ctx.amount.value;
165
+ if (outcome.status === "PAID") {
166
+ const details = cardDetailsOf(outcome);
167
+ const paid = {
168
+ status: "PAID",
169
+ amount,
170
+ metadata
171
+ };
172
+ return details ? {
173
+ ...paid,
174
+ details
175
+ } : paid;
176
+ }
177
+ if (outcome.status === "PENDING") return {
178
+ status: "PENDING",
179
+ amount,
180
+ metadata
181
+ };
182
+ return failedResult(ctx, webpayErrorOf(ctx, outcome), metadata);
183
+ };
184
+ /** Spark operation failures: a lost answer may still have charged. */
185
+ const serverErrorOf = (ctx, cause) => {
186
+ const e = cause;
187
+ const extra = {
188
+ provider_message: e?.message ?? "Webpay request failed",
189
+ attempt: ctx.attempt
190
+ };
191
+ if (e?.code === "AMBIGUOUS" || e?.status === 504) return createPaymentError("AMBIGUOUS", extra);
192
+ if (e?.status === 409) return createPaymentError("INVALID_CREDENTIALS", extra);
193
+ if (e?.status === 400) return createPaymentError("INVALID_REQUEST", extra);
194
+ return createPaymentError("PROVIDER_UNAVAILABLE", extra);
195
+ };
196
+ //#endregion
197
+ //#region src/webpay.ts
198
+ const record = (value) => {
199
+ if (!value || typeof value !== "object") return {};
200
+ return value;
201
+ };
202
+ /** Webpay token this attempt recorded (PENDING or a later result). */
203
+ const tokenOf = (result) => {
204
+ const token = record(result.metadata.provider).token;
205
+ return typeof token === "string" && token ? token : null;
206
+ };
207
+ /**
208
+ * Transbank Webpay Plus (Chile) for web and apps. Spark creates the
209
+ * transaction with the commerce keys (`create`); the template opens the
210
+ * Webpay form as a payment challenge (`ui.challenge`, a form `POST` of
211
+ * `token_ws`: popup or new tab on the web, WebView in an app; Transbank
212
+ * advises against an iframe); Webpay sends the customer back to the Fire
213
+ * Spark return, which commits and closes the tender; then the adapter
214
+ * reads the result with `confirm`, which also commits when the customer
215
+ * closed the form before the return arrived. A paid charge is reversed by
216
+ * Spark with the order cancel or refund.
217
+ */
218
+ const transbankWebpayPayments = () => {
219
+ const confirm = async (ctx, token) => {
220
+ ctx.ui.message({
221
+ text: "Confirmando pago…",
222
+ kind: "waiting"
223
+ });
224
+ return webpayResultOf(ctx, await ctx.server.call("confirm", { token }));
225
+ };
226
+ /** Keeps the token on the tender: the server needs it to void. */
227
+ const withToken = (result, token) => {
228
+ const provider = {
229
+ ...record(result.metadata.provider),
230
+ token
231
+ };
232
+ return {
233
+ ...result,
234
+ metadata: {
235
+ ...result.metadata,
236
+ provider
237
+ }
238
+ };
239
+ };
240
+ const start = async (ctx) => {
241
+ if (ctx.amount.currency !== "CLP") return failedResult(ctx, createPaymentError("INVALID_REQUEST", {
242
+ provider_message: "Webpay Plus charges CLP only",
243
+ attempt: ctx.attempt
244
+ }));
245
+ const show = ctx.ui.challenge;
246
+ if (!show) return failedResult(ctx, createPaymentError("INVALID_REQUEST", {
247
+ provider_message: "The channel cannot open the Webpay form",
248
+ attempt: ctx.attempt
249
+ }));
250
+ let created;
251
+ try {
252
+ created = await ctx.server.call("create", {});
253
+ } catch (cause) {
254
+ return failedResult(ctx, serverErrorOf(ctx, cause));
255
+ }
256
+ const { token, url } = created;
257
+ ctx.ui.message({
258
+ text: "Abriendo Webpay…",
259
+ kind: "waiting"
260
+ });
261
+ const input = {
262
+ url,
263
+ method: "POST",
264
+ parameters: [{
265
+ name: "token_ws",
266
+ value: token
267
+ }],
268
+ version: WEBPAY_CHALLENGE_VERSION,
269
+ signal: ctx.signal
270
+ };
271
+ await show.call(ctx.ui, input).catch(() => ({ completed: false }));
272
+ try {
273
+ return withToken(await confirm(ctx, token), token);
274
+ } catch (cause) {
275
+ const error = serverErrorOf(ctx, cause);
276
+ const metadata = { attempt_reference: ctx.attemptReference };
277
+ return withToken(failedResult(ctx, error, metadata), token);
278
+ }
279
+ };
280
+ /** A PENDING attempt (the app came back later): read it again. */
281
+ const query = async (ctx, result) => {
282
+ if (result.status !== "PENDING") return result;
283
+ const token = tokenOf(result);
284
+ if (!token) return result;
285
+ try {
286
+ return withToken(await confirm(ctx, token), token);
287
+ } catch (cause) {
288
+ return withToken(failedResult(ctx, serverErrorOf(ctx, cause)), token);
289
+ }
290
+ };
291
+ /** Nothing was committed: nothing to void on the device. */
292
+ const cancel = async (_ctx, result) => {
293
+ return {
294
+ ...result,
295
+ status: "CANCELLED"
296
+ };
297
+ };
298
+ /**
299
+ * A paid charge is refunded by Spark with the commerce keys when the
300
+ * order is cancelled or refunded (`server`); the device does nothing.
301
+ */
302
+ const reversalFor = (result) => {
303
+ return result.status === "PAID" ? "server" : "cancel";
304
+ };
305
+ return {
306
+ provider: TRANSBANK_PROVIDER,
307
+ method: WEBPAY_METHOD,
308
+ errors: webpayErrors,
309
+ policy: WEBPAY_POLICY,
310
+ start,
311
+ query,
312
+ cancel,
313
+ reversalFor
314
+ };
315
+ };
316
+ //#endregion
317
+ export { TRANSBANK_PROVIDER, WEBPAY_CHALLENGE_VERSION, WEBPAY_CURRENCY, WEBPAY_METHOD, WEBPAY_POLICY, failedResult, serverErrorOf, transbankWebpayPayments, webpayCardTypeOf, webpayErrorOf, webpayErrors, webpayMetadataOf, webpayResultOf };
package/package.json CHANGED
@@ -1,6 +1,59 @@
1
1
  {
2
2
  "name": "@fire-spark/payments-transbank-webpay",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.17.3",
4
+ "description": "Fire Spark Transbank Webpay Plus adapter (Chile): card payments from the web and apps through the Webpay form, committed by Fire Spark",
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/payments": "^0.17.3",
21
+ "@fire-spark/types": "^0.17.3"
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.