@mandarvl/vanilla-pay-international 1.0.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Manda Ravalison
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# @mandarvl/vanilla-pay-international
+
+A Node.js SDK for **Vanilla Pay International API**, supporting payments via mobile money, international cards, and more.
+
+## Installation
+
+```bash
+npm install @mandarvl/vanilla-pay-international
+```
+
+---
+
+## Usage
+
+### 1. Setup environment variables
+
+After creating and generating your keys from Vanilla Pay International, in your environment variables, add these :
+
+```env
+CLIENT_ID=your_client_id
+CLIENT_SECRET=your_client_secret
+ENV=PROD   # or PREPROD
+```
+
+---
+
+### 2. Initialize client and make a payment
+
+```ts
+import dotenv from 'dotenv';
+import { VanillaPayInternational, Environment } from '@mandarvl/vanilla-pay-international';
+
+dotenv.config();
+
+async function main() {
+  const clientId = process.env.CLIENT_ID;
+  const clientSecret = process.env.CLIENT_SECRET;
+  const env = process.env.ENV as Environment;
+
+  if (!clientId || !clientSecret || !env) {
+    throw new Error('CLIENT_ID, CLIENT_SECRET, and ENV are required');
+  }
+
+  const vanillaPay = new VanillaPayInternational(env);
+
+  try {
+    const auth = await vanillaPay.auth.generateToken(clientId, clientSecret);
+    vanillaPay.setAccessToken(auth.Token);
+
+    const payment = await vanillaPay.payment.init({
+      amount: 10000,
+      cart: '123',
+      currency: 'MGA',
+      reference: '123',
+      paymentMethod: 'mobile_money',
+      callbackUrl: 'https://your-callback-url.com',
+      redirectUrl: 'https://your-redirect-url.com'
+    });
+
+    console.log(payment);
+
+    const paymentDetails = await vanillaPay.payment.get(payment.id);
+    console.log(paymentDetails);
+  } catch (err) {
+    console.error(err);
+  }
+}
+
+main();
+```
+
+---
+
+### 3. Handle Payment Callbacks
+
+Vanilla Pay International posts to your `callbackUrl` with headers:
+
+* `VPI-Signature`
+* `Content-Type: application/x-www-form-urlencoded`
+
+Validate the payload using:
+
+```ts
+import { Utils } from '@mandarvl/vanilla-pay-international';
+
+const isValid = Utils.formatAndValidatePayload(vpiSignature, body, keySecret);
+
+if (isValid) {
+  // process payment
+} else {
+  // invalid signature
+}
+```
+
+* `vpiSignature`: value from headers
+* `body`: payload object
+* `keySecret`: generated from your account
+
+---
+
+### 4. Supported Payment Methods
+
+* `mobile_money` (Mvola, Orange Money, Airtel Money, etc.)
+* `international` (Visa, Mastercard, PayPal)
+
+---
+
+### 5. License
+
+MIT © Manda Ravalison

package/dist/auth.d.ts

@@ -0,0 +1,6 @@
+import { Service } from "./shared/service";
+import { AuthResponse } from "./shared/type";
+declare class AuthService extends Service {
+    generateToken(clientId: string, clientSecret: string): Promise<AuthResponse>;
+}
+export default AuthService;

package/dist/auth.js

@@ -0,0 +1,32 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const service_1 = require("./shared/service");
+class AuthService extends service_1.Service {
+    generateToken(clientId, clientSecret) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const { data } = yield this.httpClient.get("/webpayment/token", {
+                    headers: {
+                        'Client-Id': clientId,
+                        'Client-Secret': clientSecret
+                    }
+                });
+                return data.Data;
+            }
+            catch (error) {
+                throw ((_a = error === null || error === void 0 ? void 0 : error.response) === null || _a === void 0 ? void 0 : _a.data) || (error === null || error === void 0 ? void 0 : error.response) || error;
+            }
+        });
+    }
+}
+exports.default = AuthService;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import VanillaPayInternational from "./vanilla-pay-international";
+import PaymentService from "./payment";
+import { Util } from "./shared/util";
+import { Environment, PaymentRequest, PaymentResponse, AuthResponse, PaymentStatus, PaymentDetails, PaymentMethod } from "./shared/type";
+export { VanillaPayInternational, PaymentService, Util, Environment, PaymentMethod, PaymentRequest, PaymentResponse, PaymentStatus, PaymentDetails, AuthResponse };

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentStatus = exports.Util = exports.PaymentService = exports.VanillaPayInternational = void 0;
+const vanilla_pay_international_1 = __importDefault(require("./vanilla-pay-international"));
+exports.VanillaPayInternational = vanilla_pay_international_1.default;
+const payment_1 = __importDefault(require("./payment"));
+exports.PaymentService = payment_1.default;
+const util_1 = require("./shared/util");
+Object.defineProperty(exports, "Util", { enumerable: true, get: function () { return util_1.Util; } });
+const type_1 = require("./shared/type");
+Object.defineProperty(exports, "PaymentStatus", { enumerable: true, get: function () { return type_1.PaymentStatus; } });

package/dist/payment.d.ts

@@ -0,0 +1,7 @@
+import { Service } from "./shared/service";
+import { PaymentDetails, PaymentRequest, PaymentResponse } from "./shared/type";
+declare class PaymentService extends Service {
+    init(payData: PaymentRequest): Promise<PaymentResponse>;
+    get(id: string): Promise<PaymentDetails>;
+}
+export default PaymentService;

package/dist/payment.js

@@ -0,0 +1,53 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const const_1 = require("./shared/const");
+const service_1 = require("./shared/service");
+const util_1 = require("./shared/util");
+class PaymentService extends service_1.Service {
+    init(payData) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const payload = {
+                    montant: payData.amount,
+                    reference: payData.reference,
+                    panier: payData.cart,
+                    notif_url: payData.callbackUrl,
+                    redirect_url: payData.redirectUrl,
+                    devise: payData.currency,
+                    mode_paiement: payData.paymentMethod
+                };
+                const { data } = yield this.httpClient.post(`/api/webpayment/${const_1.CURRENT_API_VERSION}/initiate`, payload);
+                return {
+                    id: data.Data.url.split('?id=')[1],
+                    url: data.Data.url
+                };
+            }
+            catch (error) {
+                throw ((_a = error === null || error === void 0 ? void 0 : error.response) === null || _a === void 0 ? void 0 : _a.data) || (error === null || error === void 0 ? void 0 : error.response) || error;
+            }
+        });
+    }
+    get(id) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const { data } = yield this.httpClient.get(`/api/webpayment/${const_1.CURRENT_API_VERSION}/status/${id}`);
+                return Object.assign(Object.assign({}, util_1.Util.formatPaymentData(data.Data)), { id });
+            }
+            catch (error) {
+                throw ((_a = error === null || error === void 0 ? void 0 : error.response) === null || _a === void 0 ? void 0 : _a.data) || (error === null || error === void 0 ? void 0 : error.response) || error;
+            }
+        });
+    }
+}
+exports.default = PaymentService;

package/dist/shared/const.d.ts

@@ -0,0 +1,4 @@
+export declare const PREPROD_URL = "https://preprod.vanilla-pay.net/";
+export declare const PROD_URL = "https://bo.vanilla-pay.net/";
+export declare const CURRENT_API_VERSION = "v2";
+export declare const CURRENT_VPI_VERSION = "2023-01-12";

package/dist/shared/const.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURRENT_VPI_VERSION = exports.CURRENT_API_VERSION = exports.PROD_URL = exports.PREPROD_URL = void 0;
+exports.PREPROD_URL = 'https://preprod.vanilla-pay.net/';
+exports.PROD_URL = 'https://bo.vanilla-pay.net/';
+exports.CURRENT_API_VERSION = 'v2';
+exports.CURRENT_VPI_VERSION = '2023-01-12';

package/dist/shared/service.d.ts

@@ -0,0 +1,9 @@
+import { AxiosInstance } from 'axios';
+import VanillaPayInternational from '../vanilla-pay-international';
+export declare class Service {
+    protected httpClient: AxiosInstance;
+    protected vanillaPay: VanillaPayInternational;
+    constructor(httpClient: AxiosInstance, vanillaPay: VanillaPayInternational);
+    setAccessToken(accessToken: string): void;
+    private setOptions;
+}

package/dist/shared/service.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Service = void 0;
+class Service {
+    constructor(httpClient, vanillaPay) {
+        this.httpClient = httpClient;
+        this.setOptions();
+        this.vanillaPay = vanillaPay;
+    }
+    setAccessToken(accessToken) {
+        this.httpClient.defaults.headers.common["Authorization"] = `${accessToken}`;
+    }
+    setOptions() {
+        this.httpClient.defaults.headers.common['Date'] = new Date().toUTCString();
+        this.httpClient.defaults.headers.common['Cache-Control'] = 'no-cache';
+    }
+}
+exports.Service = Service;

package/dist/shared/type.d.ts

@@ -0,0 +1,42 @@
+export type Environment = 'PREPROD' | 'PROD';
+export type PaymentMethod = 'international' | 'mobile_money';
+export interface ApiResponse<T> {
+    CodeRetour: number;
+    DescRetour: string;
+    DetailRetour: string;
+    Data: T;
+}
+export interface AuthResponse {
+    Token: string;
+}
+export interface PaymentRequest {
+    amount: number;
+    reference: string;
+    currency: 'MGA' | 'EUR';
+    cart: string;
+    callbackUrl: string;
+    redirectUrl: string;
+    paymentMethod: PaymentMethod;
+}
+export interface PaymentResponse {
+    id: string;
+    url: string;
+}
+export declare enum PaymentStatus {
+    INITIATED = "INITIATED",
+    SUCCESS = "SUCCESS",
+    PENDING = "PENDING",
+    FAILED = "FAILED"
+}
+export interface PaymentDetails {
+    id?: string;
+    amount: number;
+    receivedAmount?: number;
+    reference: string;
+    vpiReference: string;
+    status: PaymentStatus;
+    cart?: string;
+    paymentMethod: PaymentMethod;
+    phoneNumber?: string;
+    mobileMoneyReference?: string;
+}

package/dist/shared/type.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentStatus = void 0;
+var PaymentStatus;
+(function (PaymentStatus) {
+    PaymentStatus["INITIATED"] = "INITIATED";
+    PaymentStatus["SUCCESS"] = "SUCCESS";
+    PaymentStatus["PENDING"] = "PENDING";
+    PaymentStatus["FAILED"] = "FAILED";
+})(PaymentStatus || (exports.PaymentStatus = PaymentStatus = {}));

package/dist/shared/util.d.ts

@@ -0,0 +1,6 @@
+import { PaymentDetails } from "./type";
+export declare class Util {
+    static formatAndValidatePayload(vpiSignature: string, body: any, keySecret: string): PaymentDetails | false;
+    static formatPaymentData(data: any): PaymentDetails;
+    private static hashData;
+}

package/dist/shared/util.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Util = void 0;
+const crypto_1 = require("crypto");
+class Util {
+    static formatAndValidatePayload(vpiSignature, body, keySecret) {
+        const bodyString = JSON.stringify(body);
+        const hashedData = Util.hashData(keySecret, bodyString);
+        const isValid = hashedData.toLowerCase() === vpiSignature.toLowerCase();
+        if (!isValid)
+            return false;
+        return {
+            vpiReference: body.reference_VPI,
+            cart: body.panier,
+            reference: body.reference,
+            amount: body.montant,
+            status: body.etat,
+            paymentMethod: body.referenceMM ? 'mobile_money' : 'international',
+            phoneNumber: body.initiateur,
+            mobileMoneyReference: body.referenceMM
+        };
+    }
+    static formatPaymentData(data) {
+        return {
+            vpiReference: data.reference_VPI,
+            cart: data.panier,
+            reference: data.reference,
+            amount: data.montant,
+            receivedAmount: data.montantRecu,
+            status: data.etat,
+            paymentMethod: data.referenceMM ? 'mobile_money' : 'international',
+            phoneNumber: data.initiateur,
+            mobileMoneyReference: data.referenceMM
+        };
+    }
+    static hashData(key, payload) {
+        const hashedData = (0, crypto_1.createHmac)('SHA256', key).update(payload).digest('hex');
+        return hashedData;
+    }
+}
+exports.Util = Util;

package/dist/vanilla-pay-international.d.ts

@@ -0,0 +1,12 @@
+import PaymentService from "./payment";
+import AuthService from "./auth";
+import { Environment } from "./shared/type";
+declare class VanillaPayInternational {
+    payment: PaymentService;
+    auth: AuthService;
+    environment: Environment;
+    constructor(environment: Environment);
+    setAccessToken(accessToken: string): void;
+    private getUrl;
+}
+export default VanillaPayInternational;

package/dist/vanilla-pay-international.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const axios_1 = __importDefault(require("axios"));
+const payment_1 = __importDefault(require("./payment"));
+const auth_1 = __importDefault(require("./auth"));
+const const_1 = require("./shared/const");
+class VanillaPayInternational {
+    constructor(environment) {
+        const client = axios_1.default.create({
+            baseURL: this.getUrl(environment),
+            headers: {
+                'Accept': '*/*',
+                'VPI-VERSION': const_1.CURRENT_VPI_VERSION
+            }
+        });
+        this.environment = environment;
+        this.payment = new payment_1.default(client, this);
+        this.auth = new auth_1.default(client, this);
+    }
+    setAccessToken(accessToken) {
+        this.payment.setAccessToken(accessToken);
+    }
+    getUrl(environment) {
+        return environment === 'PREPROD' ? const_1.PREPROD_URL : const_1.PROD_URL;
+    }
+}
+exports.default = VanillaPayInternational;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@mandarvl/vanilla-pay-international",
+  "version": "1.0.0",
+  "description": "A Node.JS package for Vanilla Pay International API",
+  "private": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "prepublishOnly": "npm run build",
+    "deploy": "npm publish --access public"
+  },
+  "author": "Manda Ravalison",
+  "keywords": [
+    "vanilla pay",
+    "vanilla pay international",
+    "online payment",
+    "visa",
+    "mastercard",
+    "paypal",
+    "mobile money",
+    "mvola",
+    "orange money",
+    "airtel money"
+  ],
+  "files": ["dist"],
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.4.0",
+    "crypto-js": "^4.1.1"
+  },
+  "devDependencies": {
+    "dotenv": "^16.4.5",
+    "@types/dotenv": "^8.2.0",
+    "@types/crypto-js": "^4.1.2",
+    "@types/node": "^20.1.4",
+    "typescript": "^5.0.4"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.js"
+    }
+  }
+}