Payriff JS/TS SDK

Unofficial JavaScript/TypeScript SDK for the Payriff Payment Gateway.

Table of Contents

• Introduction
• Requirements
• Installation
• Getting Started
  • 1. Sign Up & Activation
  • 2. Configuration
• API Reference
  • V3 Gateway (Orders, Refunds, AutoPay)
    • Create Order
    • Get Order
    • Refund
    • AutoPay (Pay with Saved Card)
  • V2 Gateway (Invoices, Transfers, Wallet)
    • Create Invoice
    • Transfer Funds
    • Topup (MPAY)
    • Card Save
• Extra Features
• License

Introduction

Payriff provides a one-stop-shop to manage your online payments, offering a secure ecosystem for businesses of all sizes. This SDK allows you to easily integrate Payriff's payment solutions into your JavaScript or TypeScript applications.

Features include:

• Strict Typing: Full TypeScript support with Zod schemas.
• Runtime Validation: Inputs are validated before requests are sent.
• Versioned API: Clear separation of V2 and V3 endpoints.

Requirements

• Node.js 16+ or modern browser environment
• A Payriff Merchant Account (Personal or Business)

Installation

npm install payriff-js

Getting Started

1. Sign Up & Activation

Before using the SDK, you must register with Payriff:

1. Sign Up: Register at payriff.com.
2. Activation: Verify your phone number to activate Test Mode.
3. Connect:
   • Personal: Instant setup for one-time payments.
   • Business: Create a merchant account for unlimited processing.
4. Get Credentials: Navigate to the Dashboard -> Applications to find your Secret Key and Merchant ID.

2. Configuration

Initialize the client with your credentials.

import { Payriff } from "payriff-js";

const client = new Payriff({
  secretKey: "YOUR_SECRET_KEY", // Required
  merchantId: "YOUR_MERCHANT_ID", // Required for V2 endpoints (Invoices, etc.)
  baseUrl: "https://api.payriff.com/api", // Optional, defaults to production
});

API Reference

The SDK is organized into client.v3 and client.v2 to match the Payriff API versions.

V3 Gateway (Orders, Refunds, AutoPay)

Use client.v3 for standard e-commerce flows (Create Order, Refund, AutoPay).

Create Order

Generate a payment link for a customer.

const response = await client.v3.createOrder({
  amount: 10.50,
  currency: "AZN",
  language: "AZ",
  description: "Order #12345",
  callbackUrl: "https://your-site.com/callback",
  operation: "PURCHASE", // or "PRE_AUTH"
  cardSave: true // Optional: Enable card saving for future AutoPay
});

console.log("Redirect URL:", response.payload.paymentUrl);
console.log("Order ID:", response.payload.orderId);

Get Order

Retrieve status and details of an order.

const order = await client.v3.getOrder("ORDER_UUID");
console.log("Status:", order.payload.paymentStatus); // "PAID", "CREATED", etc.

Refund

Refund a transaction partially or in full.

const refund = await client.v3.refund({
  orderId: "ORDER_UUID",
  amount: 5.00 // Amount to refund
});

Complete Order (Pre-Auth)

Complete a pre-authorized transaction.

const result = await client.v3.completeOrder({
  orderId: "ORDER_UUID",
  amount: 10.50
});

AutoPay (Pay with Saved Card)

Process a payment using a saved card (requires cardUuid from a previous saved transaction).

const autoPay = await client.v3.autoPay({
  cardUuid: "SAVED_CARD_UUID",
  amount: 15.00,
  currency: "AZN",
  description: "Subscription Renewal",
  callbackUrl: "https://your-site.com/callback"
});

V2 Gateway (Invoices, Transfers, Wallet)

Use client.v2 for invoicing, wallet operations, and legacy features.

Create Invoice

Send an invoice via SMS/Email or get a direct payment link.

const invoice = await client.v2.createInvoice({
  amount: 50.00,
  currencyType: "AZN",
  approveURL: "https://site.com/success",
  cancelURL: "https://site.com/cancel",
  declineURL: "https://site.com/decline",
  description: "Consulting Services",
  email: "[email protected]",
  sendEmail: true,
  sendSms: false
});

console.log("Invoice URL:", invoice.payload.paymentUrl);

Transfer Funds

Transfer funds between Payriff wallets.

const transfer = await client.v2.transfer({
  toMerchant: "RECEIVER_MERCHANT_ID",
  amount: 100.00,
  description: "Internal Transfer"
});

Topup (MPAY)

Transfer funds to an MPAY wallet.

const topup = await client.v2.topup({
  phoneNumber: "994501234567",
  amount: 20.00,
  description: "Wallet Topup"
});

Card Save

Explicitly save a card (alternative to createOrder with cardSave: true).

const cardSave = await client.v2.cardSave({
  amount: 1.00, // Verification amount
  currencyType: "AZN",
  approveURL: "https://site.com/approve",
  cancelURL: "https://site.com/cancel",
  declineURL: "https://site.com/decline",
  description: "Save Card"
});

Wallets

Check wallet balance and history.

const wallets = await client.v2.getWallets();
console.log("Total Balance:", wallets.payload.totalBalance);

Extra Features

• Dashboard: Manage your business, view analytics, and handle disputes manually via the Payriff Dashboard.
• Transactions: Filter and export transaction history as CSV reports.
• Plugins: Ready-made plugins available for WooCommerce and Opencart.

License

ISC