@fire-spark/payments-credibanco 0.0.0-stage → 0.22.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,205 @@
1
+ import { PaymentAdapter, PaymentAmount, PaymentContext, PaymentMetadata, PaymentPolicy, PaymentResult } from "@fire-spark/payments";
2
+ //#region src/constants.d.ts
3
+ declare const CREDIBANCO_PROVIDER = "credibanco";
4
+ /** AlterPay payment ways offered on `BANK_TRANSFER`. */
5
+ declare const CREDIBANCO_PROCESSORS: {
6
+ readonly pse: "PSE";
7
+ readonly bancolombia: "Botón Bancolombia";
8
+ };
9
+ type CredibancoProcessor = keyof typeof CREDIBANCO_PROCESSORS;
10
+ declare const credibancoProcessorOf: (value: unknown) => "bancolombia" | "pse" | null;
11
+ /** Processors this payment offers (`config.processors`), in catalog order. */
12
+ declare const credibancoEnabledProcessors: (config: Record<string, unknown>) => ("bancolombia" | "pse")[];
13
+ /**
14
+ * One automatic attempt (a retry is a new Credibanco order); a pending
15
+ * bank payment is read every 5 seconds for up to 30 minutes (PSE).
16
+ */
17
+ declare const CREDIBANCO_POLICY: Partial<PaymentPolicy>;
18
+ /** Device storage key of the Credibanco order of one attempt. */
19
+ declare const credibancoStorageKey: (attemptReference: string) => string;
20
+ /** `getOrderStatusExtended.do` outcomes and API codes that end unpaid. */
21
+ declare const credibancoErrors: Readonly<Record<string, import("@fire-spark/payments").PaymentErrorEntry>> & {
22
+ declined: {
23
+ code: "CARD_DECLINED";
24
+ source: string;
25
+ };
26
+ cancelled: {
27
+ code: "CANCELLED_BY_USER";
28
+ source: string;
29
+ };
30
+ amount_mismatch: {
31
+ code: "AMBIGUOUS";
32
+ source: string;
33
+ };
34
+ transfer_failed: {
35
+ code: "WALLET_REJECTED";
36
+ source: string;
37
+ };
38
+ invalid_credentials: {
39
+ code: "INVALID_CREDENTIALS";
40
+ source: string;
41
+ };
42
+ };
43
+ //#endregion
44
+ //#region src/types.d.ts
45
+ /** Card data the customer types. It goes only to the Fire Spark API. */
46
+ type CredibancoCardInput = {
47
+ number: string;
48
+ cvc: string;
49
+ expiry_month: number | string;
50
+ expiry_year: number | string;
51
+ /** `NOMBRE APELLIDO` (two words at least). */
52
+ holder_name: string;
53
+ };
54
+ /** A card the customer saved with Credibanco (no card data). */
55
+ type CredibancoSavedCard = {
56
+ id: string;
57
+ brand: string;
58
+ last4: string;
59
+ expiry_month: number;
60
+ expiry_year: number;
61
+ };
62
+ /**
63
+ * What the card form answers: a new card (saved first, then paid) or a
64
+ * saved card (`card_ref`). `cvc` of a saved card is sent when the
65
+ * merchant has no permission to pay without it.
66
+ */
67
+ type CredibancoCardForm = {
68
+ card: CredibancoCardInput;
69
+ } | {
70
+ card_ref: string;
71
+ cvc?: string;
72
+ };
73
+ /** Card form of the template (modal, sheet…). `null` = customer left. */
74
+ type CredibancoCardCollector = {
75
+ collect(input: {
76
+ amount: PaymentAmount;
77
+ /** Last error to show (declined card, invalid data…). */
78
+ error: string | null;
79
+ }): Promise<CredibancoCardForm | null>;
80
+ };
81
+ /** Where the customer goes: the bank (PSE, Bancolombia) or 3-D Secure. */
82
+ type CredibancoAction = {
83
+ type: "redirect";
84
+ url: string;
85
+ } | {
86
+ type: "form_post";
87
+ url: string;
88
+ fields: Record<string, string>;
89
+ };
90
+ /**
91
+ * Opens an action and resolves when the customer is back on `returnUrl`
92
+ * (`returned`, with Credibanco's `orderId` when the page read it), left
93
+ * (`cancelled`), or when the page itself navigated away (`redirected`:
94
+ * the attempt stays pending and the return page resumes it).
95
+ */
96
+ type CredibancoBridge = {
97
+ open(input: {
98
+ action: CredibancoAction;
99
+ attemptReference: string;
100
+ signal?: AbortSignal;
101
+ }): Promise<{
102
+ type: "returned";
103
+ mdOrder?: string | null;
104
+ } | {
105
+ type: "cancelled";
106
+ } | {
107
+ type: "redirected";
108
+ }>;
109
+ };
110
+ /** PSE payer the customer confirms (the API fills name/email/phone). */
111
+ type CredibancoPsePayer = {
112
+ user_type: "0" | "1";
113
+ doc_type: "CC" | "CE" | "PP" | "DE" | "NIT" | "ICE";
114
+ doc_number: string;
115
+ /** Payer address (PSE requires it); default: customer's delivery address. */
116
+ address?: string;
117
+ full_name?: string;
118
+ email?: string;
119
+ phone?: string;
120
+ };
121
+ type CredibancoBank = {
122
+ code: string;
123
+ name: string;
124
+ };
125
+ /** `status` answer of the API (only ids and codes). */
126
+ type CredibancoOutcome = {
127
+ status: "PAID" | "FAILED" | "CANCELLED" | "PENDING";
128
+ code?: string;
129
+ description?: string | null;
130
+ provider?: {
131
+ md_order?: string | null;
132
+ order_status?: number | null;
133
+ authorization_code?: string | null;
134
+ rrn?: string | null;
135
+ masked_pan?: string | null;
136
+ action_code?: string | null;
137
+ };
138
+ };
139
+ /** `charge_with_token` answer. */
140
+ type CredibancoChargeAnswer = {
141
+ status: "PAID" | "REQUIRES_3DS" | "FAILED";
142
+ md_order?: string | null;
143
+ provider_reference?: string | null;
144
+ authorization_code?: string | null;
145
+ rrn?: string | null;
146
+ description?: string | null;
147
+ action?: CredibancoAction;
148
+ };
149
+ //#endregion
150
+ //#region src/adapter.d.ts
151
+ type ReturnUrl = string | ((ctx: PaymentContext) => string);
152
+ type CredibancoCardOptions = {
153
+ /** Card form of the template (new card or saved card). */
154
+ collector: CredibancoCardCollector;
155
+ /** Opens the 3-D Secure challenge Credibanco asks for. */
156
+ bridge: CredibancoBridge;
157
+ /** Channel page (https) the bank sends the customer back to. */
158
+ returnUrl: ReturnUrl;
159
+ };
160
+ type CredibancoTransferOptions = {
161
+ /** Opens the bank (PSE or Botón Bancolombia). */
162
+ bridge: CredibancoBridge;
163
+ /** Channel page (https) the bank sends the customer back to. */
164
+ returnUrl: ReturnUrl;
165
+ /** Fixed processor; else the channel's pick, the only one or `ui.select`. */
166
+ processor?: CredibancoProcessor;
167
+ /**
168
+ * PSE payer (document); default asks the customer with `ui`. Name, email
169
+ * and phone default to the customer profile on the API.
170
+ */
171
+ psePayer?: (ctx: PaymentContext) => Promise<CredibancoPsePayer | null>;
172
+ selectTitle?: string;
173
+ };
174
+ /**
175
+ * Credibanco card (Colombia). The card is saved first: the template's
176
+ * form sends it to the Fire Spark API (`register_card`), which keeps only
177
+ * Credibanco's binding. The order is then paid with the saved card
178
+ * (`charge_with_token`); a 3-D Secure challenge opens with `bridge` and
179
+ * the API reads the result (`status`). Credentials stay on the API; no
180
+ * refunds or voids through this gateway (`manual`).
181
+ */
182
+ declare const credibancoCardPayments: (options: CredibancoCardOptions) => PaymentAdapter;
183
+ /**
184
+ * Credibanco bank payments (Colombia) through AlterPay: PSE (bank list,
185
+ * payer document, redirect to the bank) and Botón Bancolombia (redirect).
186
+ * The processor is `options.processor`, else the channel's pick
187
+ * (`config.processor`), else the only enabled one, else `ui.select`.
188
+ * Back on the return page the API reads the order (`status`); a pending
189
+ * PSE is read again until it ends.
190
+ */
191
+ declare const credibancoTransferPayments: (options: CredibancoTransferOptions) => PaymentAdapter;
192
+ //#endregion
193
+ //#region src/result.d.ts
194
+ /** Ids of a Credibanco order: nothing sensitive. */
195
+ declare const credibancoMetadataOf: (ctx: PaymentContext, mdOrder: string | null, outcome?: CredibancoOutcome, card?: CredibancoSavedCard | null) => PaymentMetadata;
196
+ /** PAID / FAILED / PENDING result of an API `status` answer. */
197
+ declare const credibancoResultOf: (ctx: PaymentContext, input: {
198
+ outcome: CredibancoOutcome;
199
+ mdOrder: string | null;
200
+ card?: CredibancoSavedCard | null;
201
+ processor?: CredibancoProcessor | null;
202
+ kind?: "card" | "transfer";
203
+ }) => PaymentResult;
204
+ //#endregion
205
+ export { CREDIBANCO_POLICY, CREDIBANCO_PROCESSORS, CREDIBANCO_PROVIDER, type CredibancoAction, type CredibancoBank, type CredibancoBridge, type CredibancoCardCollector, type CredibancoCardForm, type CredibancoCardInput, CredibancoCardOptions, type CredibancoChargeAnswer, type CredibancoOutcome, CredibancoProcessor, type CredibancoPsePayer, type CredibancoSavedCard, CredibancoTransferOptions, credibancoCardPayments, credibancoEnabledProcessors, credibancoErrors, credibancoMetadataOf, credibancoProcessorOf, credibancoResultOf, credibancoStorageKey, credibancoTransferPayments };
package/dist/index.js ADDED
@@ -0,0 +1,518 @@
1
+ import { PaymentError, createPaymentError, definePaymentErrors } from "@fire-spark/payments";
2
+ //#region src/constants.ts
3
+ const CREDIBANCO_PROVIDER = "credibanco";
4
+ /** AlterPay payment ways offered on `BANK_TRANSFER`. */
5
+ const CREDIBANCO_PROCESSORS = {
6
+ pse: "PSE",
7
+ bancolombia: "Botón Bancolombia"
8
+ };
9
+ const credibancoProcessorOf = (value) => {
10
+ if (typeof value !== "string") return null;
11
+ return value in CREDIBANCO_PROCESSORS ? value : null;
12
+ };
13
+ /** Processors this payment offers (`config.processors`), in catalog order. */
14
+ const credibancoEnabledProcessors = (config) => {
15
+ const list = Array.isArray(config.processors) ? config.processors : [];
16
+ return Object.keys(CREDIBANCO_PROCESSORS).filter((key) => list.includes(key));
17
+ };
18
+ /**
19
+ * One automatic attempt (a retry is a new Credibanco order); a pending
20
+ * bank payment is read every 5 seconds for up to 30 minutes (PSE).
21
+ */
22
+ const CREDIBANCO_POLICY = {
23
+ timeout_ms: 1800 * 1e3,
24
+ max_attempts: 1,
25
+ poll_interval_ms: 5e3
26
+ };
27
+ /** Device storage key of the Credibanco order of one attempt. */
28
+ const credibancoStorageKey = (attemptReference) => {
29
+ return `credibanco:order:${attemptReference}`;
30
+ };
31
+ const source = "docs/payments/credibanco/web.md#11-errores";
32
+ /** `getOrderStatusExtended.do` outcomes and API codes that end unpaid. */
33
+ const credibancoErrors = definePaymentErrors({
34
+ declined: {
35
+ code: "CARD_DECLINED",
36
+ source
37
+ },
38
+ cancelled: {
39
+ code: "CANCELLED_BY_USER",
40
+ source
41
+ },
42
+ amount_mismatch: {
43
+ code: "AMBIGUOUS",
44
+ source
45
+ },
46
+ transfer_failed: {
47
+ code: "WALLET_REJECTED",
48
+ source
49
+ },
50
+ invalid_credentials: {
51
+ code: "INVALID_CREDENTIALS",
52
+ source
53
+ }
54
+ });
55
+ //#endregion
56
+ //#region src/result.ts
57
+ const clip = (value, max) => {
58
+ return (value ?? "").trim().slice(0, max) || null;
59
+ };
60
+ /** Ids of a Credibanco order: nothing sensitive. */
61
+ const credibancoMetadataOf = (ctx, mdOrder, outcome, card) => {
62
+ const provider = outcome?.provider ?? {};
63
+ const payment = {
64
+ provider_transaction_id: mdOrder,
65
+ authorization_code: provider.authorization_code ?? null,
66
+ reference: provider.rrn ?? mdOrder,
67
+ brand: card?.brand ?? null,
68
+ last4: card?.last4 ?? null
69
+ };
70
+ const p1 = {
71
+ md_order: mdOrder,
72
+ order_status: provider.order_status ?? null
73
+ };
74
+ return {
75
+ attempt_reference: ctx.attemptReference,
76
+ payment,
77
+ provider: {
78
+ ...p1,
79
+ action_code: provider.action_code ?? null
80
+ }
81
+ };
82
+ };
83
+ const failedResult = (ctx, error, metadata) => {
84
+ const base = metadata ?? { attempt_reference: ctx.attemptReference };
85
+ const review = error.code === "AMBIGUOUS" ? { needs_review: true } : {};
86
+ const m = {
87
+ ...base,
88
+ ...review,
89
+ error
90
+ };
91
+ return {
92
+ status: "FAILED",
93
+ amount: ctx.amount.value,
94
+ metadata: m,
95
+ error
96
+ };
97
+ };
98
+ const pendingResult = (ctx, mdOrder) => {
99
+ const metadata = credibancoMetadataOf(ctx, mdOrder);
100
+ return {
101
+ status: "PENDING",
102
+ amount: ctx.amount.value,
103
+ metadata
104
+ };
105
+ };
106
+ /** Tender details: card brand/last 4, or the bank way and order id. */
107
+ const detailsOf = (card, processor, outcome, mdOrder) => {
108
+ if (card) {
109
+ const auth = clip(outcome.provider?.authorization_code, 64);
110
+ const d = {
111
+ method: "CARD",
112
+ brand: card.brand,
113
+ last4: card.last4
114
+ };
115
+ return auth ? {
116
+ ...d,
117
+ auth_code: auth
118
+ } : d;
119
+ }
120
+ const reference = clip(outcome.provider?.rrn ?? mdOrder, 128);
121
+ if (!processor || !reference) return null;
122
+ return {
123
+ method: "BANK_TRANSFER",
124
+ reference,
125
+ bank: CREDIBANCO_PROCESSORS[processor]
126
+ };
127
+ };
128
+ /** PAID / FAILED / PENDING result of an API `status` answer. */
129
+ const credibancoResultOf = (ctx, input) => {
130
+ const { outcome, mdOrder } = input;
131
+ const card = input.card ?? null;
132
+ const metadata = credibancoMetadataOf(ctx, mdOrder, outcome, card);
133
+ const amount = ctx.amount.value;
134
+ if (outcome.status === "PAID") return {
135
+ status: "PAID",
136
+ amount,
137
+ metadata,
138
+ details: detailsOf(card, input.processor ?? null, outcome, mdOrder)
139
+ };
140
+ if (outcome.status === "PENDING") return {
141
+ status: "PENDING",
142
+ amount,
143
+ metadata
144
+ };
145
+ let code = (input.kind ? input.kind === "card" : Boolean(card)) ? "CARD_DECLINED" : "WALLET_REJECTED";
146
+ if (outcome.status === "CANCELLED") code = "CANCELLED_BY_USER";
147
+ if (outcome.code === "AMOUNT_MISMATCH") code = "AMBIGUOUS";
148
+ const error = createPaymentError(code, {
149
+ provider_message: outcome.description ?? null,
150
+ attempt: ctx.attempt
151
+ });
152
+ return failedResult(ctx, error, metadata);
153
+ };
154
+ /** Spark operation failures: a missing answer may still have charged. */
155
+ const serverErrorOf = (ctx, cause) => {
156
+ const e = cause;
157
+ const extra = {
158
+ provider_message: e?.message ?? "Credibanco request failed",
159
+ attempt: ctx.attempt
160
+ };
161
+ const code = e?.code ?? e?.details?.code;
162
+ if (code === "INVALID_CREDENTIALS") return createPaymentError("INVALID_CREDENTIALS", extra);
163
+ if (code === "AMBIGUOUS" || e?.status === 504) return createPaymentError("AMBIGUOUS", extra);
164
+ if (e?.status === 400) return createPaymentError("INVALID_REQUEST", extra);
165
+ if (e?.status === 409) return createPaymentError("INVALID_REQUEST", extra);
166
+ return createPaymentError("PROVIDER_UNAVAILABLE", extra);
167
+ };
168
+ //#endregion
169
+ //#region src/adapter.ts
170
+ const text = (value) => {
171
+ return typeof value === "string" && value.trim() ? value.trim() : null;
172
+ };
173
+ const cancelled = (ctx) => {
174
+ return new PaymentError(createPaymentError("CANCELLED_BY_USER", { attempt: ctx.attempt }));
175
+ };
176
+ const returnUrlOf = (ctx, value) => {
177
+ return typeof value === "function" ? value(ctx) : value;
178
+ };
179
+ const save = (ctx, saved) => {
180
+ return ctx.storage.set(credibancoStorageKey(ctx.attemptReference), JSON.stringify(saved));
181
+ };
182
+ const load = async (ctx, result) => {
183
+ const fromResult = text((result?.metadata.provider)?.md_order);
184
+ const raw = await ctx.storage.get(credibancoStorageKey(ctx.attemptReference));
185
+ let stored = null;
186
+ try {
187
+ stored = raw ? JSON.parse(raw) : null;
188
+ } catch {
189
+ stored = null;
190
+ }
191
+ const md = fromResult ?? text(stored?.md_order);
192
+ return md ? {
193
+ ...stored,
194
+ md_order: md
195
+ } : null;
196
+ };
197
+ /** Reads the order on the API (never trusts the browser). */
198
+ const readStatus = async (ctx, saved) => {
199
+ return credibancoResultOf(ctx, {
200
+ outcome: await ctx.server.call("status", { md_order: saved.md_order }),
201
+ mdOrder: saved.md_order,
202
+ card: saved.card ?? null,
203
+ kind: saved.kind,
204
+ processor: saved.processor ?? null
205
+ });
206
+ };
207
+ /** Opens the action; back on the return page, reads the status. */
208
+ const openAndRead = async (ctx, bridge, action, saved) => {
209
+ const outcome = await bridge.open({
210
+ action,
211
+ attemptReference: ctx.attemptReference,
212
+ signal: ctx.signal
213
+ });
214
+ if (outcome.type === "redirected") return pendingResult(ctx, saved.md_order);
215
+ ctx.ui.message({
216
+ text: "Confirmando pago…",
217
+ kind: "waiting"
218
+ });
219
+ const result = await readStatus(ctx, saved);
220
+ if (outcome.type === "cancelled" && result.status === "PENDING") return failedResult(ctx, cancelled(ctx).error, result.metadata);
221
+ return result;
222
+ };
223
+ const query = async (ctx, result) => {
224
+ if (result.status !== "PENDING") return result;
225
+ const saved = await load(ctx, result);
226
+ if (!saved) return result;
227
+ try {
228
+ return await readStatus(ctx, saved);
229
+ } catch (cause) {
230
+ return failedResult(ctx, serverErrorOf(ctx, cause));
231
+ }
232
+ };
233
+ /**
234
+ * Credibanco card (Colombia). The card is saved first: the template's
235
+ * form sends it to the Fire Spark API (`register_card`), which keeps only
236
+ * Credibanco's binding. The order is then paid with the saved card
237
+ * (`charge_with_token`); a 3-D Secure challenge opens with `bridge` and
238
+ * the API reads the result (`status`). Credentials stay on the API; no
239
+ * refunds or voids through this gateway (`manual`).
240
+ */
241
+ const credibancoCardPayments = (options) => {
242
+ const start = async (ctx) => {
243
+ let error = null;
244
+ try {
245
+ for (;;) {
246
+ const form = await options.collector.collect({
247
+ amount: ctx.amount,
248
+ error
249
+ });
250
+ if (!form) throw cancelled(ctx);
251
+ let card = null;
252
+ let cardRef;
253
+ let cvc;
254
+ if ("card" in form) {
255
+ ctx.ui.message({
256
+ text: "Guardando tarjeta…",
257
+ kind: "waiting"
258
+ });
259
+ const saved = await ctx.server.call("register_card", { card: form.card });
260
+ if (saved.status !== "REGISTERED" || !saved.card) {
261
+ error = saved.description ?? "No pudimos guardar la tarjeta";
262
+ continue;
263
+ }
264
+ card = saved.card;
265
+ cardRef = saved.card.id;
266
+ cvc = form.card.cvc;
267
+ } else {
268
+ cardRef = form.card_ref;
269
+ cvc = form.cvc;
270
+ }
271
+ ctx.ui.message({
272
+ text: "Procesando pago…",
273
+ kind: "waiting"
274
+ });
275
+ const c1 = {
276
+ card_ref: cardRef,
277
+ confirmed_total: String(ctx.amount.value)
278
+ };
279
+ const c2 = { return_url: returnUrlOf(ctx, options.returnUrl) };
280
+ const answer = await ctx.server.call("charge_with_token", {
281
+ ...c1,
282
+ ...c2,
283
+ ...cvc ? { cvc } : {}
284
+ });
285
+ const mdOrder = text(answer.md_order) ?? text(answer.provider_reference);
286
+ const saved = {
287
+ md_order: mdOrder ?? "",
288
+ card,
289
+ kind: "card"
290
+ };
291
+ if (mdOrder) await save(ctx, saved);
292
+ if (answer.status === "PAID" && mdOrder) return await readStatus(ctx, saved);
293
+ if (answer.status === "REQUIRES_3DS" && mdOrder) {
294
+ if (!answer.action) return pendingResult(ctx, mdOrder);
295
+ return await openAndRead(ctx, options.bridge, answer.action, saved);
296
+ }
297
+ return failedResult(ctx, createPaymentError("CARD_DECLINED", {
298
+ provider_message: answer.description ?? null,
299
+ attempt: ctx.attempt
300
+ }), pendingResult(ctx, mdOrder).metadata);
301
+ }
302
+ } catch (cause) {
303
+ if (cause instanceof PaymentError) return failedResult(ctx, cause.error);
304
+ return failedResult(ctx, serverErrorOf(ctx, cause));
305
+ }
306
+ };
307
+ return {
308
+ provider: CREDIBANCO_PROVIDER,
309
+ method: "CARD",
310
+ errors: credibancoErrors,
311
+ policy: CREDIBANCO_POLICY,
312
+ start,
313
+ query,
314
+ reversalFor: () => "manual"
315
+ };
316
+ };
317
+ const DOC_TYPES = [
318
+ {
319
+ label: "Cédula de ciudadanía",
320
+ value: "CC"
321
+ },
322
+ {
323
+ label: "Cédula de extranjería",
324
+ value: "CE"
325
+ },
326
+ {
327
+ label: "Pasaporte",
328
+ value: "PP"
329
+ },
330
+ {
331
+ label: "Documento extranjero",
332
+ value: "DE"
333
+ },
334
+ {
335
+ label: "NIT",
336
+ value: "NIT"
337
+ },
338
+ {
339
+ label: "Identificación comercio extranjero",
340
+ value: "ICE"
341
+ }
342
+ ];
343
+ /** Default PSE payer prompt: person type, document type and number. */
344
+ const askPsePayer = async (ctx) => {
345
+ const userType = await ctx.ui.select({
346
+ title: "Tipo de persona",
347
+ options: [{
348
+ label: "Natural",
349
+ value: "0"
350
+ }, {
351
+ label: "Jurídica",
352
+ value: "1"
353
+ }]
354
+ });
355
+ const docType = await ctx.ui.select({
356
+ title: "Tipo de documento",
357
+ options: DOC_TYPES
358
+ });
359
+ const docNumber = text(await ctx.ui.input({
360
+ label: "Número de documento",
361
+ type: "text",
362
+ maxLength: 20
363
+ }));
364
+ if (!docNumber) return null;
365
+ return {
366
+ user_type: userType,
367
+ doc_type: docType,
368
+ doc_number: docNumber
369
+ };
370
+ };
371
+ /** Prompts of the PSE fields the API can report as `missing`. */
372
+ const PAYER_PROMPTS = {
373
+ clientAddress: {
374
+ key: "address",
375
+ label: "Dirección"
376
+ },
377
+ email: {
378
+ key: "email",
379
+ label: "Correo electrónico"
380
+ },
381
+ phone: {
382
+ key: "phone",
383
+ label: "Teléfono celular"
384
+ },
385
+ clientFullName: {
386
+ key: "full_name",
387
+ label: "Nombre y apellido"
388
+ }
389
+ };
390
+ /**
391
+ * Asks the PSE fields a `400 { missing }` answer names, when all of them
392
+ * can be asked; `null` otherwise (the error stands).
393
+ */
394
+ const askMissingPayer = async (ctx, cause) => {
395
+ const details = cause?.details;
396
+ const prompts = (Array.isArray(details?.missing) ? details.missing : []).map((name) => PAYER_PROMPTS[String(name)]);
397
+ if (!prompts.length || prompts.some((prompt) => !prompt)) return null;
398
+ const answers = {};
399
+ for (const prompt of prompts) {
400
+ if (!prompt) continue;
401
+ const value = text(await ctx.ui.input({
402
+ label: prompt.label,
403
+ type: "text",
404
+ maxLength: 200
405
+ }));
406
+ if (!value) throw cancelled(ctx);
407
+ answers[prompt.key] = value;
408
+ }
409
+ return answers;
410
+ };
411
+ /**
412
+ * Credibanco bank payments (Colombia) through AlterPay: PSE (bank list,
413
+ * payer document, redirect to the bank) and Botón Bancolombia (redirect).
414
+ * The processor is `options.processor`, else the channel's pick
415
+ * (`config.processor`), else the only enabled one, else `ui.select`.
416
+ * Back on the return page the API reads the order (`status`); a pending
417
+ * PSE is read again until it ends.
418
+ */
419
+ const credibancoTransferPayments = (options) => {
420
+ const pickProcessor = async (ctx) => {
421
+ const enabled = credibancoEnabledProcessors(ctx.config);
422
+ const wanted = options.processor ?? credibancoProcessorOf(ctx.config.processor);
423
+ if (wanted) return wanted;
424
+ if (enabled.length <= 1) return enabled[0] ?? null;
425
+ const picked = await ctx.ui.select({
426
+ title: options.selectTitle ?? "¿Con qué quieres pagar?",
427
+ options: enabled.map((key) => {
428
+ return {
429
+ label: CREDIBANCO_PROCESSORS[key],
430
+ value: key
431
+ };
432
+ })
433
+ });
434
+ if (!enabled.includes(picked)) throw cancelled(ctx);
435
+ return picked;
436
+ };
437
+ const start = async (ctx) => {
438
+ try {
439
+ const processor = await pickProcessor(ctx);
440
+ if (!processor) throw cancelled(ctx);
441
+ const return_url = returnUrlOf(ctx, options.returnUrl);
442
+ let input = {
443
+ processor,
444
+ return_url
445
+ };
446
+ if (processor === "pse") {
447
+ ctx.ui.message({
448
+ text: "Cargando bancos…",
449
+ kind: "waiting"
450
+ });
451
+ const first = await ctx.server.call("pse_banks", { return_url });
452
+ const bank = await ctx.ui.select({
453
+ title: "Selecciona tu banco",
454
+ options: first.banks.map((item) => {
455
+ return {
456
+ label: item.name,
457
+ value: item.code
458
+ };
459
+ })
460
+ });
461
+ const payer = await (options.psePayer ?? askPsePayer)(ctx);
462
+ if (!payer || !bank) throw cancelled(ctx);
463
+ input = {
464
+ ...input,
465
+ session: first.session,
466
+ payer: {
467
+ ...payer,
468
+ bank_code: bank
469
+ }
470
+ };
471
+ }
472
+ ctx.ui.message({
473
+ text: "Conectando con tu banco…",
474
+ kind: "waiting"
475
+ });
476
+ const create = () => {
477
+ return ctx.server.call("create_payment", input);
478
+ };
479
+ const started = await create().catch(async (cause) => {
480
+ const asked = await askMissingPayer(ctx, cause);
481
+ if (!asked) throw cause;
482
+ const payer = {
483
+ ...input.payer,
484
+ ...asked
485
+ };
486
+ input = {
487
+ ...input,
488
+ payer
489
+ };
490
+ return create();
491
+ });
492
+ const saved = {
493
+ md_order: started.md_order,
494
+ processor,
495
+ kind: "transfer"
496
+ };
497
+ await save(ctx, saved);
498
+ return await openAndRead(ctx, options.bridge, {
499
+ type: "redirect",
500
+ url: started.redirect_url
501
+ }, saved);
502
+ } catch (cause) {
503
+ if (cause instanceof PaymentError) return failedResult(ctx, cause.error);
504
+ return failedResult(ctx, serverErrorOf(ctx, cause));
505
+ }
506
+ };
507
+ return {
508
+ provider: CREDIBANCO_PROVIDER,
509
+ method: "BANK_TRANSFER",
510
+ errors: credibancoErrors,
511
+ policy: CREDIBANCO_POLICY,
512
+ start,
513
+ query,
514
+ reversalFor: () => "manual"
515
+ };
516
+ };
517
+ //#endregion
518
+ export { CREDIBANCO_POLICY, CREDIBANCO_PROCESSORS, CREDIBANCO_PROVIDER, credibancoCardPayments, credibancoEnabledProcessors, credibancoErrors, credibancoMetadataOf, credibancoProcessorOf, credibancoResultOf, credibancoStorageKey, credibancoTransferPayments };
package/package.json CHANGED
@@ -1,6 +1,59 @@
1
1
  {
2
2
  "name": "@fire-spark/payments-credibanco",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.22.0",
4
+ "description": "Fire Spark Credibanco adapters (Colombia): card saved first and paid with its binding (3-D Secure by redirect), PSE and Botón Bancolombia through AlterPay, verified by the Fire Spark API; credentials never reach the channel",
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.22.0",
21
+ "@fire-spark/types": "^0.22.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.