SDK Node.js PayUnit


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
- Table des matières
- Fonctionnalités
- Prérequis
- Installation
- Configuration
- Options de configuration
- Utilisation
- 1. Service de recouvrement
- 1.1 Lancer un paiement
- 1.2 Payer par carte
- 1.3 Effectuer un paiement (Mobile Money)
- 1.4 Initier et effectuer un paiement (Mobile Money) - Une étape
- 1.5 Obtenir le statut de la transaction
- 2. Service de paiement
- 2.1 Initialiser une session de paiement
- 2.2 Traitement du paiement
- 2.3 Obtenir le statut du paiement
- 3. Service Factures
- 3.1 Créer une facture standard
- 3.2 Créer une facture échelonnée
- 3.3 Payer une facture
- 3.4 Obtenir une facture
- 4. Service de versements
- 4.1 Créer un décaissement
- 4.2 Confirmer le décaissement
- 4.3 Obtenir l'état du décaissement
- Développement
- Contribution
- 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
- Pour consulter la documentation destinée aux développeurs, cliquez ici. Documentation développeur Payunit

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
});
`

$3

| 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

$3

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 Initier et effectuer un paiement (Mobile Money) - Une étape

Cette méthode combine l'initiation et l'exécution du paiement en un seul appel pour les transactions Mobile Money :

`typescript
const paymentResult = await client.collections.initiateAndMakePaymentMobileMoney({
total_amount: 1000, // Montant
currency: 'XAF',
transaction_id: TXN_${Date.now()},
gateway: 'CM_MTNMOMO', // Obligatoire : fournisseur Mobile Money
phone_number: '6XXXXXX', // Obligatoire : numéro de téléphone du client
return_url: 'https://your-site.com/return', // Facultatif
notify_url: 'https://your-site.com/webhook', // Facultatif
payment_country: 'CM', // Facultatif
redirect_on_failed: 'yes', // Facultatif, 'yes' ou 'no'
custom_fields: {
// Champs personnalisés facultatifs
order_id: '12345',
customer_type: 'premium',
},
});
`

#### 1.5 Obtenir le statut de la transaction

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

$3

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

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');
`

$3

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 avant de soumettre des pull requests.

Licence

ISC