sibs-payments/README.md

A payment system module for SIBS payments integration with card tokenization support

# SIBS Payment System

A Node.js module for SIBS payments integration with support for multiple payment methods including card tokenization, MB WAY, and MB Reference payments.

## Features

- **Card Payments**: Process payments using card tokens
- **Card Tokenization**: Save card information securely for future payments
- **MB WAY Payments**: Process payments via MB WAY mobile app
- **MB Reference Payments**: Generate payment references for bank transfers
- **Payment Status**: Check transaction status

## Installation

```bash
npm install https://github.com/Procimo/sibs-payments
```

## Usage

### Import the module

```javascript
import payments from 'sibs-payments';
```

### Card Tokenization

Save a card for future payments:

```javascript
const iam = {
    clientId: "YOUR_SIBS_CLIENT_ID",
    terminalId: 12345, // Note: terminalId is a number
    bearerToken: "YOUR_SIBS_TOKEN_BEARER",
}

const data = {
    id: "custom-id",
    description: "Saving Card",
    PAN: "4111111111111111",
    secureCode: "123",
    validationDate: "12/25",
    customerName: "John Doe",
    customerEmail: "john@example.com",
    billingAddress: {
        street1: "Rua da Graça",
        street2: "",
        city: "Lisbon",
        postcode: "1200-999",
        country: "PT"
    }
};

const result = await payments.SaveCard(iam, data);
```

### Card Payment with Token

Process a payment using a saved card token:

```javascript
const iam = {
    clientId: "YOUR_SIBS_CLIENT_ID",
    terminalId: 12345,
    bearerToken: "YOUR_SIBS_TOKEN_BEARER",
}

const data = {
    id: "custom-id",
    description: "Card Payment",
    token: "saved_card_token_here",
    secureCode: "123",
    currency: "EUR",
    value: 100.00,
    customerName: "John Doe",
    customerEmail: "john@example.com",
    billingAddress: {
        street1: "Rua da Graça",
        street2: "",
        city: "Lisbon",
        postcode: "1200-999",
        country: "PT"
    }
};

const result = await payments.Card(iam, data);
```

### MB WAY Payment

Process a payment via MB WAY:

```javascript
const iam = {
    clientId: "YOUR_SIBS_CLIENT_ID",
    terminalId: 12345,
    bearerToken: "YOUR_SIBS_TOKEN_BEARER",
}

const data = {
    id: "custom-id",
    description: "MB Way Payment",
    phone: "351#912345678",
    currency: "EUR",
    value: 50.00,
};

const result = await payments.MbWay(iam, data);
```

### MB Reference Payment

Generate a payment reference for bank transfer:

```javascript
const iam = {
    clientId: "YOUR_SIBS_CLIENT_ID",
    terminalId: 12345,
    bearerToken: "YOUR_SIBS_TOKEN_BEARER",
}

const data = {
    id: "custom-id",
    description: "MB Ref Payment",
    entity: "12345",
    currency: "EUR",
    value: 50.00,
};

const result = await payments.MbRef(iam, data);
```

### Check Payment Status

Check the status of a transaction:

```javascript
const iam = {
    clientId: "YOUR_SIBS_CLIENT_ID",
    terminalId: 12345,
    bearerToken: "YOUR_SIBS_TOKEN_BEARER",
}

const status = await payments.Status(iam, transactionId);
```

## Configuration

You'll need the following credentials from SIBS:

- `clientId`: Your client ID (string)
- `terminalId`: Your terminal ID (number)
- `bearerToken`: Your authentication bearer token (string)

## Data Types

### IAM
```typescript
interface IAM {
    clientId: string;
    terminalId: number;
    bearerToken: string;
}
```

### Address
```typescript
interface Address {
    street1: string;
    street2: string;
    city: string;
    postcode: string;
    country: string;
}
```

### SaveCardData
```typescript
interface SaveCardData {
    id: string;
    PAN: string;
    validationDate: string;
    customerName: string;
    customerEmail: string;
    secureCode?: string;
    billingAddress?: Address;
    description?: string;
}
```

### CardData
```typescript
interface CardData {
    id: string;
    token: string;
    value: number;
    currency: string;
    customerName: string;
    customerEmail: string;
    secureCode?: string;
    billingAddress?: Address;
    description?: string;
}
```

### MbWayData
```typescript
interface MbWayData {
    id: string;
    description: string;
    phone: string;
    currency: string;
    value: number;
}
```

### MbRefData

```typescript
interface MbRefData {
    id: string;
    description: string;
    entity: string;
    currency: string;
    value: number;
}
```


## Development

```bash
# Install dependencies
npm install

# Build the project
npm run build
```

## License

ISC