@payunit/nodejs-sdk/Readme.fr.md

PayUnit Payment Processor SDK

# SDK Node.js PayUnit

[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)

Un SDK TypeScript/Node.js pour l'intégration à la passerelle de paiement PayUnit. Ce SDK offre un moyen simple et sécurisé de traiter les paiements, de gérer les factures, de gérer les encaissements et de traiter les décaissements dans vos applications Node.js.

## Table des matières

- [SDK Node.js PayUnit](#sdk-nodejs-payunit)
  - [Table des matières](#table-des-matières)
  - [Fonctionnalités](#fonctionnalités)
  - [Prérequis](#prérequis)
  - [Installation](#installation)
  - [Configuration](#configuration)
    - [Options de configuration](#options-de-configuration)
  - [Utilisation](#utilisation)
    - [1. Service de recouvrement](#1-service-de-recouvrement)
      - [1.1 Lancer un paiement](#11-lancer-un-paiement)
      - [1.2 Payer par carte](#12-payer-par-carte)
      - [1.3 Effectuer un paiement (Mobile Money)](#13-effectuer-un-paiement-mobile-money)
      - [1.4 Obtenir le statut de la transaction](#14-obtenir-le-statut-de-la-transaction)
    - [2. Service de paiement](#2-service-de-paiement)
      - [2.1 Initialiser une session de paiement](#21-initialiser-une-session-de-paiement)
      - [2.2 Traitement du paiement](#22-traitement-du-paiement)
      - [2.3 Obtenir le statut du paiement](#23-obtenir-le-statut-du-paiement)
    - [3. Service Factures](#3-service-factures)
      - [3.1 Créer une facture standard](#31-créer-une-facture-standard)
      - [3.2 Créer une facture échelonnée](#32-créer-une-facture-échelonnée)
      - [3.3 Payer une facture](#33-payer-une-facture)
      - [3.4 Obtenir une facture](#34-obtenir-une-facture)
    - [4. Service de versements](#4-service-de-versements)
      - [4.1 Créer un décaissement](#41-créer-un-décaissement)
      - [4.2 Confirmer le décaissement](#42-confirmer-le-décaissement)
      - [4.3 Obtenir l'état du décaissement](#43-obtenir-létat-du-décaissement)
  - [Développement](#développement)
  - [Contribution](#contribution)
  - [Licence](#licence)

## Fonctionnalités

- **Communication API sécurisée** : Chiffrement et authentification intégrés
- **Version sémantique** : Suivi de la version sémantique pour un meilleur contrôle des versions
- **Prise en charge TypeScript** : Définitions TypeScript complètes pour une meilleure expérience de développement, types de requêtes et de réponses
- **Multiples modes de paiement** : Prise en charge des paiements par carte et de l'argent mobile
- **Validation côté client** : Validation intégrée des requêtes et des réponses
- **Collections** : Traitement et vérification des paiements Transactions
- **Déboursements** : Lancez et gérez les paiements
- **Paiement** : Intégration transparente du paiement avec URL de réussite/d'annulation personnalisables
- **Factures** : Créez et gérez les demandes de paiement avec prise en charge des paiements normaux et échelonnés

## Prérequis

- Node.js 18.x ou version ultérieure
- npm 9.x ou version ultérieure
- Un compte marchand PayUnit avec les identifiants API. Cliquez ici pour obtenir les identifiants. [Payunit Mechant](https://pu.payunit.net)
- Pour consulter la documentation destinée aux développeurs, cliquez ici. [Documentation développeur Payunit](https://developer.payunit.net)

## Installation

```bash
# Utilisation de npm
npm install @payunit/nodejs-sdk

# Ou utilisation de Yarn
yarn add @payunit/nodejs-sdk

# Ou utilisation de pnpm
pnpm add @payunit/nodejs-sdk
```

## Configuration

Créez un objet de configuration avec vos identifiants d'API PayUnit :

```typescript
import { PayunitClient } from '@payunit/nodejs-sdk';

// Initialiser avec la configuration
const client = new PayunitClient({
  baseURL: 'https://gateway.payunit.net', // facultatif
  apiKey: 'your_api_key',
  apiUsername: 'your_api_username',
  apiPassword: 'your_api_password',
  mode: 'test', // ou 'live',
  timeout: 10000, // facultatif
});
```

### Options de configuration

| Option        | Type               | Obligatoire | Par défaut                    | Description                                           |
| ------------- | ------------------ | ----------- | ----------------------------- | ----------------------------------------------------- |
| `baseURL`     | `string`           | Non         | `https://gateway.payunit.net` | URL de base de l'API PayUnit                          |
| `apiKey`      | `string`           | Oui         | -                             | Votre clé API PayUnit                                 |
| `apiUsername` | `string`           | Oui         | -                             | Votre nom d'utilisateur API PayUnit                   |
| `apiPassword` | `string`           | Oui         | -                             | Votre mot de passe API PayUnit                        |
| `mode`        | `'test' \| 'live'` | Oui         | -                             | Mode d'environnement API (soit 'test', soit 'live')   |
| `timeout`     | `number`           | Non         | `10000`                       | Délai d'expiration de la requête API en millisecondes |

## Utilisation

### 1. Service de recouvrement

Le service de recouvrement gère le recouvrement des paiements et la gestion des transactions.

#### 1.1 Lancer un paiement

```typescript
const payment = await client.collections.initiatePayment({
  total_amount: 1000, // Montant
  Currency: 'XAF',
  transaction_id: `TXN_${Date.now()}`,
  return_url: 'https://your-site.com/return',
  notify_url: 'https://your-site.com/webhook',
  payment_country: 'CM', // Facultatif
  pay_with: 'CM_MTNMOMO', // Facultatif
  redirect_on_failed: 'YES', // Facultatif, 'YES' ou 'NO'
  custom_fields: {
    // Champs personnalisés facultatifs
    order_id: '12345',
    custom_type: 'premium',
  },
});
```

#### 1.2 Payer par carte

Pour payer par carte, vous devez d'abord initier la demande de paiement comme suit :

```typescript
const payment = await client.collections.initiatePayment({
  total_amount: 1000, // Montant
  currency: 'XAF',
  transaction_id: `TXN_${Date.now()}`,
  return_url: 'https://your-site.com/return',
  notify_url: 'https://your-site.com/webhook',
  payment_country: 'CM', // Facultatif
  pay_with: 'CM_MTNMOMO', // Facultatif
  redirect_on_failed: 'YES', // Facultatif, 'YES' ou 'NO'
  custom_fields: {
    // Champs personnalisés facultatifs
    order_id: '12345',
    customer_type: 'premium',
  },
});
```

Puis rediriger vers `transaction_url` sur le web pour finaliser le paiement de notre côté.

#### 1.3 Effectuer un paiement (Mobile Money)

```typescript
const paymentResult = await client.collections.makePayment({
  amount: 1000,
  gateway: 'CM_MTNMOMO', // or 'CM_ORANGE'
  currency: 'XAF',
  transaction_id: 'TXN_123456',
  phone_number: '6XXXXXX',
  return_url: 'https://your-site.com/return',
  notify_url: 'https://your-site.com/webhook',
});
```

#### 1.4 Obtenir le statut de la transaction

```typescript
const status = await client.collections.getTransactionStatus('TXN_123456');
```

### 2. Service de paiement

Le service de paiement vous permet de créer des sessions de paiement et de traiter les paiements.

#### 2.1 Initialiser une session de paiement

```typescript
const checkoutSession = await client.checkout.initialize({
  cancel_url: 'https://your-site.com/cancel',
  success_url: 'https://your-site.com/success',
  notify_url: 'https://your-site.com/webhook', // Facultatif
  currency: 'XAF',
  mode: 'payment', // ou 'subscription'
  transaction_id: `TXN_${Date.now()}`,
  total_amount: 1000, // Montant dans la plus petite unité monétaire (par exemple, centimes)
  payment_country: 'CM', // Facultatif
  items: [
    {
      price_description: {
        unit_amount: 100,
      },
      product_description: {
        name: 'Test Item',
        image_url: 'https://example.com/image.jpg',
        about_product: 'Description du produit test',
      },
      quantity: 1,
    },
  ],
  customer: {
    name: 'John Doe',
    email: 'john@example.com',
    phone: '6XXXXXX',
  },
  meta: {
    phone_number_collection: true,
    address_collection: true,
  },
});
```

#### 2.2 Traitement du paiement

```typescript
const paymentResult = await client.checkout.processPayment({
  checkout_id: checkoutSession.checkoutId,
  customer: {
    email: 'john@example.com',
    phone: '6XXXXXX',
    country: 'CM',
    name: 'John Doe',
  },
  shipping: {
    address: '123 Test St',
    phone: '6XXXXXX',
    payment_method: 'CM_MTNMOMO',
    payment_info: {
      phone: '6XXXXXX',
    },
  },
});
```

#### 2.3 Obtenir le statut du paiement

```typescript
const status = await client.checkout.getStatus('checkout_123');
```

### 3. Service Factures

Le service Factures vous permet de créer et de gérer vos factures de paiement.

#### 3.1 Créer une facture standard

```typescript
const invoice = await client.invoice.createInvoice({
client_name: 'John Doe',
client_email: 'john@example.com',
client_phone_number: '6XXXXXX',
due_date: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
partial_payment: false,
is_custom_company: false,
type: 'NORMAL',
currency: 'XAF',
callback_url: 'https://your-site.com/callback',
items: [
{
name: 'Service Fee',
amount: 1000,
quantity: 1,
},
],
// Société de facturation personnalisée facultative
custom_billing_company: {
name: 'Your Entreprise',
logo : 'https://votre-entreprise.com/logo.png',
e-mail : 'facturation@votre-entreprise.com',
numéro de téléphone : '6XXXXXX',
},
});
```

#### 3.2 Créer une facture échelonnée

```typescript
const invoice = await client.invoice.createInvoice({
client_name: 'John Doe',
client_email: 'john@example.com',
client_phone_number: '6XXXXXX',
due_date: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
partial_payment: true,
type: 'INSTALLMENT',
currency: 'XAF',
callback_url: 'https://your-site.com/callback',
items: [
{
name: 'Versement échelonné',
amount: 3000,
quantity: 1,
},
],
installments: [
{ title: 'Versement 1', due_date: '2023-07-01', montant : 1 000 },
{ titre : 'Versement 2', date d'échéance : '2023-08-01', montant : 1 000 },
{ titre : 'Versement 3', date d'échéance : '2023-09-01', montant : 1 000 },
],
});
```

#### 3.3 Payer une facture

```typescript
const invoicePayment = await client.invoice.payInvoice({
invoice_id: 'INV_123456', // invoice.uuid
montant : 1 000,
devise : 'XAF',
callback_url: 'https://your-site.com/callback', // facultatif
installment_id: 'INS_123456',
, // si le type de facture est un versement, UUID du versement
});
```

#### 3.4 Obtenir une facture

```typescript
const invoiceDetails = await client.invoice.getInvoice('INV_123456');
```

### 4. Service de versements

Le service de versements vous permet d'envoyer de l'argent vers des comptes bancaires ou des portefeuilles mobiles.

#### 4.1 Créer un décaissement

```typescript
const décaissement = await client.disbursement.createDisbursement({
devise_destination : 'XAF',
devise_débit : 'XAF',
numéro_compte : '2376XXXXXX',
montant : 1 000,
nom_bénéficiaire : 'Jean Dupont',
type_dépôt : 'ARGENT_MOBILE',
identifiant_transaction : `DISB_${Date.now()}`,
pays : 'CM',
banque_compte : 'CM_MTNMOMO', // ou 'CM_ORANGE'.
});
```

#### 4.2 Confirmer le décaissement

```typescript
const confirmation = await client.disbursement.confirmDisbursement({
  pay_token: disbursement.pay_token,
  deposit_message: 'Paiement des services',
  deposit_note: 'Merci pour votre service',
  notify_url: 'https://your-site.com/webhook',
});
```

#### 4.3 Obtenir l'état du décaissement

```typescript
const status = await client.disbursement.getDisbursementStatus('DISB_123456');
```

## Développement

1. Cloner le dépôt
2. Installer les dépendances : `npm install`
3. Générer le projet : `npm run build`
4. Exécuter les tests : `npm test`
5. Exécuter le linter : `npm run lint`
6. Exécuter le formatter : `npm run format`
7. Exécuter avant publication : `npm run beforePublish` pour tester l'ensemble du code et du processus

## Contribution

Les contributions sont les bienvenues ! Veuillez lire nos [consignes de contribution](CONTRIBUTING.md) avant de soumettre des pull requests.

## Licence

ISC