Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: lucrise-llc/azul-ts
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: v1.2.0
Choose a base ref
...
head repository: lucrise-llc/azul-ts
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: main
Choose a head ref

Commits on May 5, 2024

  1. fix: Adds types to dist

    luis-herasme committed May 5, 2024
    Copy the full SHA
    8209995 View commit details
  2. build: update package.json

    crisog committed May 5, 2024
    Copy the full SHA
    36e059c View commit details
  3. fix: trigger deployment

    crisog committed May 5, 2024
    Copy the full SHA
    34e7b04 View commit details
  4. Copy the full SHA
    c88e46a View commit details
  5. fix: trigger release

    crisog committed May 5, 2024
    Copy the full SHA
    f437e35 View commit details
  6. tests: migrate to vitest

    crisog committed May 5, 2024
    Copy the full SHA
    29fc5f0 View commit details
  7. Copy the full SHA
    37e5c2a View commit details
  8. tests: add vitest config

    crisog committed May 5, 2024
    Copy the full SHA
    88228f6 View commit details
  9. build: fix npm run test

    crisog committed May 5, 2024
    Copy the full SHA
    3e11113 View commit details
  10. fix: trigger release

    crisog committed May 5, 2024
    Copy the full SHA
    1ea2b12 View commit details
  11. Copy the full SHA
    0d2bc45 View commit details
  12. ci: fix release action

    crisog committed May 5, 2024
    Copy the full SHA
    d6241ec View commit details
  13. build: update tsconfig

    crisog committed May 5, 2024
    Copy the full SHA
    e20d0be View commit details
  14. Copy the full SHA
    085af97 View commit details
  15. fix: trigger release

    crisog committed May 5, 2024
    Copy the full SHA
    1aa85aa View commit details
  16. fix: trigger release

    crisog committed May 5, 2024
    Copy the full SHA
    5a1e10c View commit details

Commits on May 6, 2024

  1. build: fix exports

    crisog committed May 6, 2024
    Copy the full SHA
    ea66903 View commit details
  2. fix: trigger deployment

    crisog committed May 6, 2024
    Copy the full SHA
    18361a7 View commit details
  3. build: fix build imports

    crisog committed May 6, 2024
    Copy the full SHA
    c9a524c View commit details
  4. fix: trigger release

    crisog committed May 6, 2024
    Copy the full SHA
    fe74385 View commit details

Commits on May 11, 2024

  1. feat: Adds 3Ds

    luis-herasme committed May 11, 2024
    Copy the full SHA
    a776486 View commit details
  2. test: Fix search test

    luis-herasme committed May 11, 2024
    Copy the full SHA
    9296b06 View commit details

Commits on May 12, 2024

  1. fix: export some types

    crisog committed May 12, 2024
    Copy the full SHA
    3d6ec3b View commit details
  2. fix: export all types

    crisog committed May 12, 2024
    Copy the full SHA
    0a8c5a9 View commit details

Commits on May 13, 2024

  1. fix: termUrl

    luis-herasme committed May 13, 2024
    Copy the full SHA
    b7f5c4b View commit details

Commits on Aug 24, 2024

  1. build(deps): bump undici from 6.15.0 to 6.19.2 (#11)

    Bumps [undici](https://github.com/nodejs/undici) from 6.15.0 to 6.19.2.
    - [Release notes](https://github.com/nodejs/undici/releases)
    - [Commits](nodejs/undici@v6.15.0...v6.19.2)
    
    ---
    updated-dependencies:
    - dependency-name: undici
      dependency-type: direct:production
    ...
    
    Signed-off-by: dependabot[bot] <support@github.com>
    Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
    dependabot[bot] authored Aug 24, 2024
    Copy the full SHA
    3b36164 View commit details
  2. refactor: no files for cert/key (#10)

    * refactor: no files for cert/key
    
    * tests: fix azul config
    
    * build: fix action
    crisog authored Aug 24, 2024
    Copy the full SHA
    32cf412 View commit details
  3. Copy the full SHA
    9e1ec14 View commit details

Commits on Oct 16, 2024

  1. fix: examples

    crisog committed Oct 16, 2024
    Copy the full SHA
    013eb1a View commit details
  2. Copy the full SHA
    ff6f1a6 View commit details

Commits on Dec 4, 2024

  1. Copy the full SHA
    af3c8d7 View commit details
  2. Copy the full SHA
    d108891 View commit details
  3. Copy the full SHA
    b2ba5b4 View commit details

Commits on Dec 5, 2024

  1. Copy the full SHA
    86b5e14 View commit details

Commits on Dec 14, 2024

  1. Copy the full SHA
    ea22c0e View commit details
  2. Copy the full SHA
    e8703c0 View commit details

Commits on Dec 19, 2024

  1. Copy the full SHA
    589e1d9 View commit details
  2. Copy the full SHA
    01c6039 View commit details
  3. fix: vault typo

    crisog committed Dec 19, 2024
    Copy the full SHA
    bc8ff4a View commit details
  4. fix: azul ts type exports

    crisog committed Dec 19, 2024
    Copy the full SHA
    e7ce0a3 View commit details
  5. chore: trigger release

    crisog committed Dec 19, 2024
    Copy the full SHA
    e3c7c1f View commit details

Commits on Dec 26, 2024

  1. Copy the full SHA
    0a8c6d7 View commit details

Commits on Jan 29, 2025

  1. feat(core): enhance DataVault integration, certificate handling, and …

    …test suite (#12)
    
    BREAKING CHANGE: This is not compatible with our latest release.
    
    * feat(config): add certificate handling and configuration
    
    - Added new `config.ts` for centralized configuration management
    - Added `check-certificates.ts` example for certificate validation
    - Updated API client to support certificate configuration
    - Enhanced `.env.sample` with certificate-related variables
    
    This improves certificate handling and provides better examples for users implementing certificate-based authentication.
    
    * refactor(data-vault): improve schema validation and type safety
    
    - Update DataVault schemas to include required fields (channel, store)
    - Add proper type definitions for Create and Delete operations
    - Improve ProcessPaymentSchema to handle DataVault tokens correctly
      - Split into BasePaymentSchema, CardPaymentSchema and TokenPaymentSchema
      - Add proper validation for token-based payments
      - Update field constraints (altMerchantName: 25 chars, dataVaultToken: 36 chars)
    - Remove DataVaultTransaction enum in favor of literal types
    - Fix documentation comments and typos
    
    * refactor(tests): standardize test assertions and card handling
    
    - Add test card fixtures with consistent test data
    - Create utility functions for common test assertions:
      - expectSuccessfulPayment
      - expectSuccessfulVerification
      - expectSuccessfulVaultResponse
      - expectSuccessfulVoid
      - expectValidationError
      - expectOrderIds
    - Update all integration tests to use shared test cards and assertions
    - Add proper type guards and response type definitions
    - Handle temporary system errors (91) gracefully with warnings
    - Improve test descriptions and organization
    
    * feat(examples): add simple payment workflow demonstration
    
    - Create new example script for end-to-end payment processing
    - Demonstrate key Azul API workflows: hold, post, and verification
    - Include environment configuration logging and error handling
    - Use test card fixture and random order ID for realistic scenario
    
    * refactor(tests): use centralized config for Azul API instance
    
    - Replace hardcoded environment variables with CONFIG import
    - Leverage centralized configuration for test API instance setup
    - Improve consistency with recent configuration management changes
    
    * test(certificates): remove redundant invalid certificate test
    
    - Remove test case for non-PEM certificate file
    - Simplify test suite by eliminating redundant error handling scenario
    - Maintain core certificate error testing logic
    
    * docs(readme): update Azul API and page configuration examples
    
    - Add environment and channel configuration options
    - Clarify certificate and key input methods
    - Update payment method example with more detailed parameters
    - Improve documentation for API initialization and usage
    gustavovalverde authored Jan 29, 2025
    Copy the full SHA
    1e8519c View commit details
  2. Copy the full SHA
    bad1568 View commit details
  3. Copy the full SHA
    07dfff9 View commit details
  4. build: remove workflow path

    crisog committed Jan 29, 2025
    Copy the full SHA
    a898ec8 View commit details

Commits on Feb 13, 2025

  1. Copy the full SHA
    937884c View commit details
  2. Copy the full SHA
    75abe18 View commit details
  3. Copy the full SHA
    d9dd71d View commit details
  4. Copy the full SHA
    54c2820 View commit details
Showing with 8,255 additions and 8,764 deletions.
  1. +18 −3 .env.sample
  2. +67 −6 .github/workflows/release.yaml
  3. +0 −38 .github/workflows/test.yaml
  4. +7 −3 .gitignore
  5. +22 −77 README.md
  6. +36 −0 eslint.config.mjs
  7. +133 −0 examples/3ds-example.ts
  8. +19 −11 examples/api-example.ts
  9. +59 −0 examples/hold-example.ts
  10. +0 −35 examples/page-example.ts
  11. +27 −0 examples/simple-example.ts
  12. +0 −5 jest.config.js
  13. +5,752 −7,059 package-lock.json
  14. +28 −13 package.json
  15. +49 −0 playwright.config.ts
  16. +59 −0 src/api.ts
  17. +0 −75 src/azul-api/api.ts
  18. +0 −68 src/azul-api/data-vault/data-vault.ts
  19. +0 −162 src/azul-api/data-vault/shemas.ts
  20. +0 −89 src/azul-api/process-payment/process-payment .ts
  21. +0 −333 src/azul-api/process-payment/schemas.ts
  22. +0 −7 src/azul-api/processes.ts
  23. +0 −110 src/azul-api/request.ts
  24. +0 −99 src/azul-api/schemas.ts
  25. +0 −158 src/azul-page.ts
  26. +99 −0 src/data-vault/data-vault.test.ts
  27. +48 −0 src/data-vault/data-vault.ts
  28. +90 −0 src/data-vault/schemas.ts
  29. +85 −0 src/hold/hold.test.ts
  30. +33 −0 src/hold/hold.ts
  31. +3 −3 src/index.ts
  32. +70 −0 src/parse-certificate/parse-certificate.test.ts
  33. +110 −0 src/parse-certificate/parse-certificate.ts
  34. +38 −0 src/post/post.test.ts
  35. +19 −0 src/post/post.ts
  36. +18 −0 src/post/schemas.ts
  37. +81 −0 src/refund/refund.test.ts
  38. +30 −0 src/refund/refund.ts
  39. +31 −0 src/refund/schemas.ts
  40. +89 −0 src/request.ts
  41. +55 −0 src/sale/sale.test.ts
  42. +25 −0 src/sale/sale.ts
  43. +85 −0 src/sale/schemas.ts
  44. +16 −0 src/schemas.ts
  45. +42 −0 src/search/schemas.ts
  46. +37 −0 src/search/search.test.ts
  47. +19 −0 src/search/search.ts
  48. +29 −0 src/secure/challenge.ts
  49. +34 −0 src/secure/method.ts
  50. +61 −0 src/secure/sale.ts
  51. +36 −0 src/secure/schemas.ts
  52. +144 −0 src/secure/secure.ts
  53. +211 −0 src/secure/types.ts
  54. +69 −0 src/tests/fixtures/cards.ts
  55. +3 −0 src/tests/fixtures/test-cert.crt
  56. +3 −0 src/tests/fixtures/test-key.key
  57. +26 −0 src/tests/instance.ts
  58. +3 −0 src/utils/assert-never.ts
  59. +2 −6 src/{utils.ts → utils/capitalize.ts}
  60. +50 −0 src/utils/make-idempotent.ts
  61. +5 −0 src/utils/sleep.ts
  62. +8 −0 src/verify/schemas.ts
  63. +27 −0 src/verify/verify.test.ts
  64. +24 −0 src/verify/verify.ts
  65. +41 −0 src/void/void.test.ts
  66. +23 −0 src/void/void.ts
  67. +31 −0 tests/3ds.spec.ts
  68. +0 −52 tests/integration/hold.test.ts
  69. +0 −44 tests/integration/post.test.ts
  70. +0 −90 tests/integration/refund.test.ts
  71. +0 −26 tests/integration/sale.test.ts
  72. +0 −43 tests/integration/search.test.ts
  73. +0 −56 tests/integration/vault.test.ts
  74. +0 −38 tests/integration/verify.test.ts
  75. +0 −53 tests/integration/void.test.ts
  76. +12 −2 tsconfig.json
  77. +14 −0 vitest.config.ts
21 changes: 18 additions & 3 deletions .env.sample
Original file line number Diff line number Diff line change
@@ -1,3 +1,18 @@
# Payment Page
AZUL_MERCHANT_ID="your-merchant-id"
AZUL_AUTH_KEY="your-auth-key"
# Authentication
AUTH1=your_auth1_here
AUTH2=your_auth2_here
MERCHANT_ID=your_merchant_id_here

# Certificates - can be file paths or certificate content
# Option 1: File paths (relative to project root or absolute paths)
AZUL_CERT=certs/azul.crt
AZUL_KEY=certs/azul.key

# Option 2: Direct certificate content
# For multiline certificates, use \n for line breaks and quote the entire string
# AZUL_CERT="-----BEGIN CERTIFICATE-----\nMIIE/zCCA...\n...more lines...\n-----END CERTIFICATE-----"
# AZUL_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQIBAD...\n...more lines...\n-----END PRIVATE KEY-----"

# Option 3: Base64 encoded certificates (if needed)
# AZUL_CERT_BASE64=LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...
# AZUL_KEY_BASE64=LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0t...
73 changes: 67 additions & 6 deletions .github/workflows/release.yaml
Original file line number Diff line number Diff line change
@@ -1,17 +1,76 @@
name: Release
name: Test and Release
on:
push:
branches:
- main
paths:
- 'src/**'
- 'tests/**'
- '.github/workflows/release.yaml'
branches: [main, master]
pull_request:
paths:
- 'src/**'
- 'tests/**'
- '.github/workflows/release.yaml'
branches: [main, master]

permissions:
contents: read

jobs:
e2e-tests:
name: Run E2E tests
timeout-minutes: 60
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 'lts/*'
- name: Install dependencies
run: npm ci
- name: Install Playwright Browsers
run: npx playwright install --with-deps
- name: Run Playwright tests
env:
AUTH1: ${{ secrets.AUTH1 }}
AUTH2: ${{ secrets.AUTH2 }}
AUTH1_3DS: ${{ secrets.AUTH1_3DS }}
AUTH2_3DS: ${{ secrets.AUTH2_3DS }}
MERCHANT_ID: ${{ secrets.MERCHANT_ID }}
AZUL_KEY: ${{ secrets.AZUL_KEY }}
AZUL_CERT: ${{ secrets.AZUL_CERT }}
run: npx playwright test
- uses: actions/upload-artifact@v4
if: always()
with:
name: playwright-report
path: playwright-report/
retention-days: 30

integration-tests:
name: Run integration tests
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 'lts/*'
- run: npm ci
- name: Run tests
env:
AUTH1: ${{ secrets.AUTH1 }}
AUTH2: ${{ secrets.AUTH2 }}
AUTH1_3DS: ${{ secrets.AUTH1_3DS }}
AUTH2_3DS: ${{ secrets.AUTH2_3DS }}
MERCHANT_ID: ${{ secrets.MERCHANT_ID }}
AZUL_KEY: ${{ secrets.AZUL_KEY }}
AZUL_CERT: ${{ secrets.AZUL_CERT }}
run: npm run test

release:
name: Release
needs: [integration-tests, e2e-tests]
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
runs-on: ubuntu-latest
permissions:
contents: write
@@ -26,13 +85,15 @@ jobs:
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: "lts/*"
node-version: 'lts/*'
- name: Install dependencies
run: npm clean-install
- name: Verify the integrity of provenance attestations and registry signatures for installed dependencies
- name: Verify the integrity of provenance attestations and registry signatures
run: npm audit signatures
- name: Build
run: npm run build
- name: Release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
run: npx semantic-release
run: npx semantic-release
38 changes: 0 additions & 38 deletions .github/workflows/test.yaml

This file was deleted.

10 changes: 7 additions & 3 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
dist
node_modules
.env
*.key
*.pem
*.crt
coverage

# Playwright
/test-results/
/playwright-report/
/blob-report/
/playwright/.cache/
99 changes: 22 additions & 77 deletions README.md
Original file line number Diff line number Diff line change
@@ -19,7 +19,7 @@ It provides a simple and intuitive interface for interacting with the Azul API,

## Features

- Support for both Azul Payment Page and API (WebService)
- Support for Azul Payment API (WebService)
- Type-safe request and response handling.
- Throughly tested and documented.

@@ -31,73 +31,9 @@ $ npm install @lucrise/azul-ts

## Usage

### Payment Page

To use the Azul Payment page, you need to initialize the `AzulPage` class with your merchant ID, auth key, merchant name, merchant type, and environment.

```typescript
import AzulPage from '../azul-page';

const azul = new AzulPage({
merchantId: process.env.MERCHANT_ID!,
authKey: process.env.AUTH_KEY!,
merchantName: 'RapidoTickets',
merchantType: 'Ecommerce'
});
```

The `merchantId` is the merchant ID provided by Azul.<br/>
The `authKey` is the authentication key provided by Azul.<br/>
The `merchantName` is the name of the merchant.<br/>
The `merchantType` is the type of merchant (e.g. Ecommerce, Retail, etc.).<br/>
The `environment` is the environment in which the merchant is operating (e.g. dev, prod, etc.).<br/>

Then, you can create a form that will redirect the user to the Azul Payment Page.

For example, let's assume you are calling the `createForm` from the frontend after clicking the "Pay now" button.

You'd need to pass the following parameters to the `createForm` function:

```typescript
import express from 'express';

const app = express();

app.get('/pay-now', async (req, res) => {
res.send(
azul.createForm({
orderNumber: req.query.orderNumber,
amount: req.query.amount,
ITBIS: req.query.ITBIS,
approvedUrl: 'https://rapidotickets.com/approved',
declinedUrl: 'https://rapidotickets.com/declined',
cancelUrl: 'https://rapidotickets.com/canceled'
})
);
});

app.listen(3000);
```

Upon submitting the form, the user will be redirected to the Azul Payment Page, where they can enter their payment information and complete the transaction.

This form is invisible to the user, it only serves as a way to redirect them to the Azul Payment Page.

![Azul Payment Page](.github/azul-payment-page.png)

Depending whether the transaction was successful or not, you'll need to redirect the user to the appropriate route.

The `approvedUrl`, `declinedUrl`, and `cancelUrl` parameters are used to specify the URLs that the user will be redirected to after a successful or unsuccessful transaction. You'll need to handle these escenarios accordingly.

Let's assume the user successfully completes the transaction. The user will be redirected to the `approvedUrl` route with the following query parameters:

```
https://rapidotickets.com/?OrderNumber=1234&Amount=1000&Itbis=100&AuthorizationCode=OK7433&DateTime=20240502233454&ResponseCode=ISO8583&IsoCode=00&ResponseMessage=APROBADA&ErrorDescription=&RRN=2024050223345744343807&AuthHash=ead90f9eecf951f612a11bb6f722786ea2c68b78a147f40a13a7ec4be9ee0bd315eee55a5a96169e61516155e4b66c39ad764338de87c24b7ac88bf819965596&CustomOrderId=&CardNumber=54241802****1732&DataVaultToken=&DataVaultExpiration=&DataVaultBrand=&AzulOrderId=44343807&DCCOffered=1&DCCApplied=0&DCCCurrency=840&DCCCurrencyAlpha=USD&DCCExchangeRate=00185&DCCMarkup=500&DCCAmount=019&Discounted=0
```

## API (WebService)

To use the Azul API, you need to initialize the `AzulAPI` class with your merchant ID, auth keys, certificate path, and key path.
To use the Azul API, you need to initialize the `AzulAPI` class with your merchant ID, auth keys, and certificates.

```typescript
import AzulAPI from '@lucrise/azul-ts';
@@ -106,15 +42,19 @@ const azul = new AzulAPI({
auth1: 'your-auth1',
auth2: 'your-auth2',
merchantId: 'your-merchant-id',
certificatePath: 'your-certificate-path',
keyPath: 'your-key-path'
certificate: 'path/to/certificate.crt',
key: 'path/to/private.key',
environment: 'dev',
channel: 'EC'
});
```

The `auth1` and `auth2` are the authentication credentials provided by Azul.<br/>
The `merchantId` is the merchant ID provided by Azul.<br/>
The `certificatePath` is the path to the certificate sent to youby Azul.<br/>
The `keyPath` is the path to the private key that generated the CSR file you sent to Azul in order to obtain the certificate.<br/>
The `certificate` is the certificate sent to you by Azul. Can be provided as a file path or PEM content directly.<br/>
The `key` is the private key that generated the CSR file. Can be provided as a file path or PEM content directly.<br/>
The `environment` determines which Azul endpoint to use ('dev' or 'prod'). Defaults to 'dev'.<br/>
The `channel` is the payment channel code provided by Azul. Defaults to 'EC'.<br/>

Then, you can use the `AzulAPI` class to make requests to the Azul API.

@@ -127,12 +67,17 @@ const app = express();

app.get('/pay-now', async (req, res) => {
const result = await azul.payments.sale({
cardNumber: req.query.cardNumber,
expiration: req.query.expiration,
CVC: req.query.CVC,
customOrderId: req.query.customOrderId,
amount: req.query.amount,
ITBIS: req.query.ITBIS
cardNumber: req.query.cardNumber, // Card number without spaces or special chars
expiration: req.query.expiration, // Format: YYYYMM (e.g., 202412)
CVC: req.query.CVC, // 3 or 4 digits
amount: req.query.amount, // Integer. Last 2 digits are decimals (e.g., 1000 = $10.00)
ITBIS: req.query.ITBIS, // Integer. Last 2 digits are decimals (e.g., 100 = $1.00)
customOrderId: req.query.customOrderId, // Optional. Max 75 chars. Used for payment verification
orderNumber: req.query.orderNumber, // Optional. Max 15 chars
channel: 'EC', // Optional. Defaults to 'EC'
posInputMode: 'E-Commerce', // Optional. Defaults to 'E-Commerce'
saveToDataVault: '2', // Optional. '1' to save card, '2' to not save
altMerchantName: 'My Store' // Optional. Max 25 chars. Shown in card statement
});

res.send(result);
@@ -141,7 +86,7 @@ app.get('/pay-now', async (req, res) => {
app.listen(3000);
```

Unlike the Payment Page, the API does not require a redirection or any sort of form. It straights send your transaction data to the Azul WebService and result is returned in the response.
The API does not require a redirection or any sort of form. It straights send your transaction data to the Azul WebService and result is returned in the response.

**NOTE: It is heavily recomended to set the `timeout` for this request to at least 120 seconds.**

36 changes: 36 additions & 0 deletions eslint.config.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
import globals from 'globals';
import pluginJs from '@eslint/js';
import tseslint from 'typescript-eslint';
import perfectionist from 'eslint-plugin-perfectionist';

export default [
{
files: ['**/*.{js,mjs,cjs,ts}']
},
{
languageOptions: {
globals: globals.node
}
},
pluginJs.configs.recommended,
...tseslint.configs.strict,
{
rules: {
'@typescript-eslint/explicit-function-return-type': 'error'
}
},
{
plugins: {
perfectionist
},
rules: {
'perfectionist/sort-imports': [
'error',
{
type: 'line-length',
order: 'asc'
}
]
}
}
];
Loading