@payunit/nodejs-sdk

v1.3.0

Published

2 months ago

PayUnit Payment Processor SDK

0High
0Medium
0Low

it-manager

payment sdk collections disbursement invoice checkout

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

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

# 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 :

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

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 :

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)

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 :

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

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

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: '[email protected]',
    phone: '6XXXXXX',
  },
  meta: {
    phone_number_collection: true,
    address_collection: true,
  },
});

2.2 Traitement du paiement

const paymentResult = await client.checkout.processPayment({
  checkout_id: checkoutSession.checkoutId,
  customer: {
    email: '[email protected]',
    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

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

const invoice = await client.invoice.createInvoice({
client_name: 'John Doe',
client_email: '[email protected]',
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 : '[email protected]',
numéro de téléphone : '6XXXXXX',
},
});

3.2 Créer une facture échelonnée

const invoice = await client.invoice.createInvoice({
client_name: 'John Doe',
client_email: '[email protected]',
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

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

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

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

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

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

Développement

Cloner le dépôt
Installer les dépendances : npm install
Générer le projet : npm run build
Exécuter les tests : npm test
Exécuter le linter : npm run lint
Exécuter le formatter : npm run format
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