tonder-web-sdk 1.16.6-beta.DEV-1433.2 → 1.16.7
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/README.md +171 -16
- package/package.json +1 -1
- package/types/checkout.d.ts +2 -0
- package/types/common.d.ts +2 -2
- package/types/mercado_pago.d.ts +62 -0
- package/v1/bundle.min.js +1 -1
package/README.md
CHANGED
|
@@ -14,9 +14,10 @@ Tonder SDK helps to integrate the services Tonder offers in your own website
|
|
|
14
14
|
4. [Styling InlineCheckout](#styling-inlinecheckout)
|
|
15
15
|
5. [Payment Data Structure](#payment-data-structure)
|
|
16
16
|
6. [Field Validation Functions](#field-validation-functions)
|
|
17
|
-
7. [
|
|
18
|
-
8. [
|
|
19
|
-
9. [
|
|
17
|
+
7. [HMAC Signature Validation](#hmac-signature-validation)
|
|
18
|
+
8. [API Reference](#api-reference)
|
|
19
|
+
9. [Examples](#examples)
|
|
20
|
+
10. [License](#license)
|
|
20
21
|
|
|
21
22
|
## Installation
|
|
22
23
|
|
|
@@ -74,6 +75,10 @@ const inlineCheckout = new InlineCheckout({
|
|
|
74
75
|
apiKey: "your-api-key",
|
|
75
76
|
returnUrl: "https://your-website.com/checkout",
|
|
76
77
|
styles: customStyles, // Optional, see Styling section
|
|
78
|
+
signatures: {
|
|
79
|
+
transaction: "nA6nQXxQ....=", // Optional HMAC signature for transaction
|
|
80
|
+
customer: "2EVYDI0H5l5v4....=" // Optional HMAC signature for card-related ops
|
|
81
|
+
}
|
|
77
82
|
});
|
|
78
83
|
|
|
79
84
|
// The configureCheckout function allows you to set initial information,
|
|
@@ -110,6 +115,10 @@ import { LiteCheckout } from "tonder-web-sdk";
|
|
|
110
115
|
const liteCheckout = new LiteCheckout({
|
|
111
116
|
apiKey: "your-api-key", // Your api key getted from Tonder Dashboard
|
|
112
117
|
returnUrl: "http://your-website.com/checkout",
|
|
118
|
+
signatures: {
|
|
119
|
+
transaction: "nA6nQXxQ....=", // Optional HMAC signature for transaction
|
|
120
|
+
customer: "2EVYDI0H5l5v4....=" // Optional HMAC signature for card-related ops
|
|
121
|
+
}
|
|
113
122
|
});
|
|
114
123
|
|
|
115
124
|
// The configureCheckout function allows you to set initial information,
|
|
@@ -153,14 +162,15 @@ const verificationResult = await liteCheckout.verify3dsTransaction();
|
|
|
153
162
|
## Configuration
|
|
154
163
|
### Inline Options
|
|
155
164
|
|
|
156
|
-
| Property | Type | Required | Description
|
|
157
|
-
|
|
158
|
-
| mode | string | Yes | Environment mode for the SDK
|
|
159
|
-
| apiKey | string | Yes | Your Tonder Public API key
|
|
160
|
-
| returnUrl | string | Yes | URL for 3DS redirect completion
|
|
161
|
-
| styles | object | No |
|
|
162
|
-
| customization | CustomizationOptions | No | UI customization options
|
|
163
|
-
| callbacks | IInlineCallbacks | No | Payment process callback functions
|
|
165
|
+
| Property | Type | Required | Description | Default | Description |
|
|
166
|
+
|:-------------:|:--------------------:|----------|-----------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------:|
|
|
167
|
+
| mode | string | Yes | Environment mode for the SDK | stage | Environment mode. Options: 'stage', 'production', 'sandbox'. Default: 'stage' |
|
|
168
|
+
| apiKey | string | Yes | Your Tonder Public API key | | Your API key from the Tonder Dashboard |
|
|
169
|
+
| returnUrl | string | Yes | URL for 3DS redirect completion | | URL where the checkout form is mounted (used for 3DS) |
|
|
170
|
+
| styles | object | No | | | (InlineCheckout only) Custom styles for the checkout interface |
|
|
171
|
+
| customization | CustomizationOptions | No | UI customization options | `{displayMode: 'light',saveCards: {showSaveCardOption: false,showSaved: false,autoSave: false,},paymentButton: {show: false,text: "Pagar",showAmount: true,},cancelButton: {show: false,text: "Cancelar",},paymentMethods: {show: true,},cardForm: {show: true,},showMessages: true,}` | Object to customize the checkout behavior and UI. |
|
|
172
|
+
| callbacks | IInlineCallbacks | No | Payment process callback functions |
|
|
173
|
+
| signatures | object | No | HMAC signatures for transaction and customer fields |
|
|
164
174
|
<details>
|
|
165
175
|
<summary>View Interface Definition</summary>
|
|
166
176
|
|
|
@@ -170,6 +180,10 @@ interface IInlineCheckoutBaseOptions {
|
|
|
170
180
|
apiKey: string;
|
|
171
181
|
returnUrl: string;
|
|
172
182
|
callBack?: (response: any) => void;
|
|
183
|
+
signatures?:{
|
|
184
|
+
transaction?: string;
|
|
185
|
+
customer?: string;
|
|
186
|
+
}
|
|
173
187
|
}
|
|
174
188
|
interface IInlineCheckoutOptions extends IInlineCheckoutBaseOptions {
|
|
175
189
|
styles?: Record<string, string>;
|
|
@@ -250,11 +264,12 @@ export type CustomizationOptions = {
|
|
|
250
264
|
|
|
251
265
|
## Lite Options
|
|
252
266
|
|
|
253
|
-
|
|
|
254
|
-
|
|
255
|
-
|
|
|
256
|
-
|
|
|
257
|
-
| returnUrl
|
|
267
|
+
| Property | Type | Required | Description | Default | Description |
|
|
268
|
+
|:----------:|:------:|----------|---------------------------------|---------|:-----------------------------------------------------------------------------:|
|
|
269
|
+
| mode | string | Yes | Environment mode for the SDK | stage | Environment mode. Options: 'stage', 'production', 'sandbox'. Default: 'stage' |
|
|
270
|
+
| apiKey | string | Yes | Your Tonder Public API key | | Your API key from the Tonder Dashboard |
|
|
271
|
+
| returnUrl | string | Yes | URL for 3DS redirect completion | | URL where the checkout form is mounted (used for 3DS) |
|
|
272
|
+
| signatures | object | No | HMAC signatures | | Provide transaction/customer HMAC if your merchant configuration requires it. |
|
|
258
273
|
|
|
259
274
|
|
|
260
275
|
## Styling InlineCheckout
|
|
@@ -354,8 +369,63 @@ When calling the `payment` method, use the following data structure:
|
|
|
354
369
|
|
|
355
370
|
- **payment_method**: (for LiteCheckout) String indicating the alternative payment method to be used (e.g., "Spei"). This is only used when not paying with a card.
|
|
356
371
|
|
|
372
|
+
- **apm_config**: (Optional) Configuration object for APM-specific options. Only applicable when using alternative payment methods like Mercado Pago.
|
|
373
|
+
<details>
|
|
374
|
+
<summary>APM Config Fields</summary>
|
|
375
|
+
|
|
376
|
+
| **Field** | **Type** | **Description** |
|
|
377
|
+
|-------------------------------------|--------------------------------------------|---------------------------------------------------------------------------|
|
|
378
|
+
| `binary_mode` | `boolean` | If `true`, payment must be approved or rejected immediately (no pending). |
|
|
379
|
+
| `additional_info` | `string` | Extra info shown during checkout and in payment details. |
|
|
380
|
+
| `back_urls` | `object` | URLs to redirect the user after payment. |
|
|
381
|
+
| └─ `success` | `string` | Redirect URL after successful payment. |
|
|
382
|
+
| └─ `pending` | `string` | Redirect URL after pending payment. |
|
|
383
|
+
| └─ `failure` | `string` | Redirect URL after failed/canceled payment. |
|
|
384
|
+
| `auto_return` | `"approved"` \| `"all"` | Enables auto redirection after payment completion. |
|
|
385
|
+
| `payment_methods` | `object` | Payment method restrictions and preferences. |
|
|
386
|
+
| └─ `excluded_payment_methods[]` | `array` | List of payment methods to exclude. |
|
|
387
|
+
| └─ `excluded_payment_methods[].id` | `string` | ID of payment method to exclude (e.g., "visa"). |
|
|
388
|
+
| └─ `excluded_payment_types[]` | `array` | List of payment types to exclude. |
|
|
389
|
+
| └─ `excluded_payment_types[].id` | `string` | ID of payment type to exclude (e.g., "ticket"). |
|
|
390
|
+
| └─ `default_payment_method_id` | `string` | Default payment method (e.g., "master"). |
|
|
391
|
+
| └─ `installments` | `number` | Max number of installments allowed. |
|
|
392
|
+
| └─ `default_installments` | `number` | Default number of installments suggested. |
|
|
393
|
+
| `expires` | `boolean` | Whether the preference has expiration. |
|
|
394
|
+
| `expiration_date_from` | `string` (ISO 8601) | Start of validity period (e.g. `"2025-01-01T12:00:00-05:00"`). |
|
|
395
|
+
| `expiration_date_to` | `string` (ISO 8601) | End of validity period. |
|
|
396
|
+
| `differential_pricing` | `object` | Configuration for differential pricing. |
|
|
397
|
+
| └─ `id` | `number` | ID of the differential pricing strategy. |
|
|
398
|
+
| `marketplace` | `string` | Marketplace identifier (default: "NONE"). |
|
|
399
|
+
| `marketplace_fee` | `number` | Fee to collect as marketplace commission. |
|
|
400
|
+
| `tracks[]` | `array` | Ad tracking configurations. |
|
|
401
|
+
| └─ `type` | `"google_ad"` \| `"facebook_ad"` | Type of tracker. |
|
|
402
|
+
| └─ `values.conversion_id` | `string` | Google Ads conversion ID. |
|
|
403
|
+
| └─ `values.conversion_label` | `string` | Google Ads label. |
|
|
404
|
+
| └─ `values.pixel_id` | `string` | Facebook Pixel ID. |
|
|
405
|
+
| `statement_descriptor` | `string` | Text on payer’s card statement (max 16 characters). |
|
|
406
|
+
| `shipments` | `object` | Shipping configuration. |
|
|
407
|
+
| └─ `mode` | `"custom"` \| `"me2"` \| `"not_specified"` | Type of shipping mode. |
|
|
408
|
+
| └─ `local_pickup` | `boolean` | Enable pickup at local branch (for `me2`). |
|
|
409
|
+
| └─ `dimensions` | `string` | Package dimensions (e.g. `10x10x10,500`). |
|
|
410
|
+
| └─ `default_shipping_method` | `number` | Default shipping method (for `me2`). |
|
|
411
|
+
| └─ `free_methods[]` | `array` | Shipping methods offered for free (for `me2`). |
|
|
412
|
+
| └─ `free_methods[].id` | `number` | ID of free shipping method. |
|
|
413
|
+
| └─ `cost` | `number` | Shipping cost (only for `custom` mode). |
|
|
414
|
+
| └─ `free_shipping` | `boolean` | If `true`, shipping is free (`custom` only). |
|
|
415
|
+
| └─ `receiver_address` | `object` | Shipping address. |
|
|
416
|
+
| └─ `receiver_address.zip_code` | `string` | ZIP or postal code. |
|
|
417
|
+
| └─ `receiver_address.street_name` | `string` | Street name. |
|
|
418
|
+
| └─ `receiver_address.street_number` | `number` | Street number. |
|
|
419
|
+
| └─ `receiver_address.city_name` | `string` | City name. |
|
|
420
|
+
| └─ `receiver_address.state_name` | `string` | State name. |
|
|
421
|
+
| └─ `receiver_address.country_name` | `string` | Country name. |
|
|
422
|
+
| └─ `receiver_address.floor` | `string` | Floor (optional). |
|
|
423
|
+
| └─ `receiver_address.apartment` | `string` | Apartment or unit (optional). |
|
|
424
|
+
</details>
|
|
425
|
+
|
|
357
426
|
Note: The exact fields required may vary depending on whether you're using InlineCheckout or LiteCheckout, and the specific payment method being used.
|
|
358
427
|
|
|
428
|
+
|
|
359
429
|
```javascript
|
|
360
430
|
const paymentData = {
|
|
361
431
|
customer: {
|
|
@@ -442,6 +512,91 @@ if (
|
|
|
442
512
|
}
|
|
443
513
|
```
|
|
444
514
|
|
|
515
|
+
## HMAC Signature Validation
|
|
516
|
+
|
|
517
|
+
Tonder supports **HMAC** validation to ensure the data sent from your application to Tonder is not tampered with.
|
|
518
|
+
|
|
519
|
+
### Overview
|
|
520
|
+
|
|
521
|
+
- **HMAC**: A cryptographic method used to validate the integrity of transmitted data.
|
|
522
|
+
- You receive an **API Secret Key** from Tonder.
|
|
523
|
+
- You generate the HMAC signature locally (SHA-256, Base64) based on certain fields.
|
|
524
|
+
- Tonder compares your signature with its own calculation.
|
|
525
|
+
- If invalid, Tonder returns a **403**.
|
|
526
|
+
|
|
527
|
+
### Generating the HMAC Signature (JavaScript Example)
|
|
528
|
+
> **Important**: This HMAC generation should be done on your **backend** server, not in client-side code, to keep your secret key secure.
|
|
529
|
+
```javascript
|
|
530
|
+
const crypto = require('crypto');
|
|
531
|
+
|
|
532
|
+
function generateHMAC(secretKey, requestBody) {
|
|
533
|
+
// Convert the payload to a JSON string.
|
|
534
|
+
// Ensure the fields are in alphabetical order if required by your config.
|
|
535
|
+
const dataString = JSON.stringify(requestBody);
|
|
536
|
+
|
|
537
|
+
// Create HMAC using SHA-256, then Base64-encode it.
|
|
538
|
+
return crypto
|
|
539
|
+
.createHmac('sha256', secretKey)
|
|
540
|
+
.update(dataString)
|
|
541
|
+
.digest('base64');
|
|
542
|
+
}
|
|
543
|
+
|
|
544
|
+
// Example usage.
|
|
545
|
+
const secretKey = "<MERCHANT_SECRET_KEY>";
|
|
546
|
+
const requestBody = {
|
|
547
|
+
customer: {
|
|
548
|
+
email: "user@example.com",
|
|
549
|
+
firstName: "John",
|
|
550
|
+
lastName: "Doe",
|
|
551
|
+
},
|
|
552
|
+
currency: "mxn",
|
|
553
|
+
cart: {
|
|
554
|
+
total: 100,
|
|
555
|
+
items: [
|
|
556
|
+
{
|
|
557
|
+
amount_total: 100,
|
|
558
|
+
description: "Sample Item",
|
|
559
|
+
},
|
|
560
|
+
],
|
|
561
|
+
},
|
|
562
|
+
};
|
|
563
|
+
|
|
564
|
+
const signature = generateHMAC(secretKey, requestBody);
|
|
565
|
+
console.log("Generated HMAC:", signature);
|
|
566
|
+
```
|
|
567
|
+
|
|
568
|
+
### Providing the Signature in the SDK
|
|
569
|
+
|
|
570
|
+
If using the Tonder SDK, include your generated signature in the `signatures` field:
|
|
571
|
+
|
|
572
|
+
```javascript
|
|
573
|
+
const inlineCheckout = new InlineCheckout({
|
|
574
|
+
mode: "development",
|
|
575
|
+
apiKey: "<YOUR_API_KEY>",
|
|
576
|
+
returnUrl: "https://your-website.com/checkout",
|
|
577
|
+
signatures: {
|
|
578
|
+
transaction: "<Base64 HMAC>", // For payment
|
|
579
|
+
customer: "<Base64 HMAC>" // For card ops
|
|
580
|
+
}
|
|
581
|
+
});
|
|
582
|
+
```
|
|
583
|
+
|
|
584
|
+
The SDK will handle attaching the signature to outgoing requests. If the signature does not match Tonder’s validation, the request will be rejected.
|
|
585
|
+
|
|
586
|
+
### Providing the Signature in Direct Calls (Without the SDK)
|
|
587
|
+
|
|
588
|
+
If you call Tonder’s REST endpoints directly, add headers:
|
|
589
|
+
|
|
590
|
+
- `X-Signature-Transaction: <Base64 HMAC>`
|
|
591
|
+
- `X-Client-Source: <merchant>-sdk` (the agreed-upon source)
|
|
592
|
+
|
|
593
|
+
### Important Notes
|
|
594
|
+
|
|
595
|
+
- Always ensure your JSON structure matches what Tonder expects.
|
|
596
|
+
- If you are required to sign specific fields, confirm you’re only signing those fields **in alphabetical order**.
|
|
597
|
+
- A mismatch results in a **403**.
|
|
598
|
+
|
|
599
|
+
|
|
445
600
|
## API Reference
|
|
446
601
|
|
|
447
602
|
### InlineCheckout Methods
|
package/package.json
CHANGED
package/types/checkout.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { ICustomer } from "./customer";
|
|
2
|
+
import { IMPConfigRequest } from "./mercado_pago";
|
|
2
3
|
|
|
3
4
|
export interface IStartCheckoutRequestBase {
|
|
4
5
|
name: any;
|
|
@@ -105,6 +106,7 @@ export interface IProcessPaymentRequest {
|
|
|
105
106
|
currency?: string;
|
|
106
107
|
payment_method?: string;
|
|
107
108
|
card?: ICardFields | string;
|
|
109
|
+
apm_config?: IMPConfigRequest | Record<string, any>;
|
|
108
110
|
}
|
|
109
111
|
|
|
110
112
|
export interface ICardFields {
|
package/types/common.d.ts
CHANGED
|
@@ -6,10 +6,10 @@ export interface IInlineCheckoutBaseOptions {
|
|
|
6
6
|
apiKey: string;
|
|
7
7
|
returnUrl: string;
|
|
8
8
|
callBack?: (response: any) => void;
|
|
9
|
-
signatures?:{
|
|
9
|
+
signatures?: {
|
|
10
10
|
transaction?: string;
|
|
11
11
|
customer?: string;
|
|
12
|
-
}
|
|
12
|
+
};
|
|
13
13
|
}
|
|
14
14
|
|
|
15
15
|
export interface IConfigureCheckout extends Partial<IProcessPaymentRequest> {
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
export interface IMPConfigRequest {
|
|
2
|
+
payment_methods?: IMPPreferencePaymentMethod;
|
|
3
|
+
binary_mode?: boolean;
|
|
4
|
+
shipments?: IMPPreferenceShipment;
|
|
5
|
+
back_urls?: IMPPreferenceBackUrl;
|
|
6
|
+
statement_descriptor?: string;
|
|
7
|
+
additional_info?: string;
|
|
8
|
+
auto_return?: "approved" | "all";
|
|
9
|
+
expires?: boolean;
|
|
10
|
+
expiration_date_from?: string;
|
|
11
|
+
expiration_date_to?: string;
|
|
12
|
+
marketplace?: string;
|
|
13
|
+
marketplace_fee?: number;
|
|
14
|
+
differential_pricing?: {
|
|
15
|
+
id: number;
|
|
16
|
+
};
|
|
17
|
+
tracks?: {
|
|
18
|
+
type: "google_ad" | "facebook_ad";
|
|
19
|
+
values: {
|
|
20
|
+
conversion_id?: string;
|
|
21
|
+
conversion_label?: string;
|
|
22
|
+
pixel_id?: string;
|
|
23
|
+
};
|
|
24
|
+
}[];
|
|
25
|
+
}
|
|
26
|
+
export interface IMPPreferencePaymentMethod {
|
|
27
|
+
excluded_payment_methods?: {
|
|
28
|
+
id: string;
|
|
29
|
+
}[];
|
|
30
|
+
excluded_payment_types?: {
|
|
31
|
+
id: string;
|
|
32
|
+
}[];
|
|
33
|
+
default_payment_method_id?: string;
|
|
34
|
+
installments?: number;
|
|
35
|
+
default_installments?: number;
|
|
36
|
+
}
|
|
37
|
+
export interface IMPPreferenceShipment {
|
|
38
|
+
mode?: "customer" | "me2" | "not_specified";
|
|
39
|
+
local_pickup?: boolean;
|
|
40
|
+
dimensions?: string;
|
|
41
|
+
default_shipping_method?: number;
|
|
42
|
+
free_methods?: {
|
|
43
|
+
id: number;
|
|
44
|
+
}[];
|
|
45
|
+
cost?: number;
|
|
46
|
+
free_shipping?: boolean;
|
|
47
|
+
receiver_address?: {
|
|
48
|
+
zip_code?: string;
|
|
49
|
+
street_name?: string;
|
|
50
|
+
city_name?: string;
|
|
51
|
+
state_name?: string;
|
|
52
|
+
street_number?: number;
|
|
53
|
+
floor?: string;
|
|
54
|
+
apartment?: string;
|
|
55
|
+
country_name?: string;
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
export interface IMPPreferenceBackUrl {
|
|
59
|
+
success?: string;
|
|
60
|
+
pending?: string;
|
|
61
|
+
failure?: string;
|
|
62
|
+
}
|