Cray Finance Node.js SDK

A first-class Node.js/TypeScript package for integrating Cray Finance APIs. This package abstracts authentication, HTTP calls, validation, retries, and error handling, providing a clean and expressive API for developers.

Requirements

• Node.js 14+
• TypeScript 4.5+ (if using TypeScript)

Installation

Install the package via npm:

npm install crayfi
# OR (assuming local)
npm install ./cray-node

Configuration

You can configure the client using environment variables or by passing arguments directly to the client.

Using Environment Variables

Create a .env file in your project root:

CRAY_API_KEY=your_api_key_here
CRAY_ENV=sandbox
CRAY_TIMEOUT=30
CRAY_RETRIES=2

Environment Switching

Set CRAY_ENV to live for production or sandbox for development/staging.

• sandbox: Uses https://dev-gateman.v3.connectramp.com
• live: Uses https://pay.connectramp.com

Usage

Import the Cray client to access all modules.

import { Cray } from "crayfi";

// Initialize the client (automatically loads from env if not provided)
const cray = new Cray("your_api_key"); 
// OR just
// const cray = new Cray(); 

1. Cards

Handle card transactions including initiation, charging, and querying.

// Initiate a card transaction
// 'reference': A unique reference for this transaction (generated by you)
// 'amount': The amount to charge (in the smallest currency unit or standard unit as per API docs)
// 'currency': The currency code (e.g., USD, NGN)
// 'card_data': Sensitive card details (PAN, CVV, Expiry)
// 'customer_information': Details about the customer initiating the transaction
const response = await cray.cards.initiate({
    reference: '4aeb118e-5009-450a-94fc-d74f6cd88646',
    amount: '100',
    currency: 'USD',
    card_data: {
        pan: '5399832641760090',
        cvv: '146',
        expiryMonth: '05',
        expiryYear: '50',
    },
    customer_information: {
        email: '[email protected]',
        firstName: 'John',
        lastName: 'Doe',
    }
});

// Process payment (Charge)
// 'transaction_id': The ID received from the initiate response or webhook
const charge = await cray.cards.charge({
    transaction_id: 'SRK4NC92PFHLGZW78A3E'
});

// Query transaction status
// 'customer_reference_id': The unique reference you provided during initiation
const status = await cray.cards.query('customer_reference_id');

2. Mobile Money (MoMo)

Process mobile money payments.

// Initiate MoMo payment
// 'payment_provider': The mobile money provider (e.g., MTN, Airtel)
// 'phone_no': The customer's phone number registered with the provider
const momo = await cray.momo.initiate({
    customer_reference: 'e4d7c3b8-5f29-4b46-81a6-8d98c1e75812',
    amount: '3950',
    currency: 'XOF',
    phone_no: '2290161248277',
    payment_provider: 'MTN',
    country: 'benin',
    firstname: 'Cray',
    lastname: 'Momo',
});

// Requery MoMo transaction
// Check the status of a transaction using your reference
const status = await cray.momo.requery('customer_reference_id');

3. Wallets

Fetch wallet balances.

// Get all wallet balances
// Returns a list of balances for all currencies in your merchant wallet
const balances = await cray.wallets.balances();

// Get subaccounts
// Returns a list of subaccounts created under your merchant account
const subaccounts = await cray.wallets.subaccounts();

4. FX & Conversions

Handle exchange rates and currency conversions.

// Get specific exchange rate
// Check the current rate between two currencies
const rate = await cray.fx.rates({
    source_currency: 'USD',
    destination_currency: 'NGN'
});

// Get rates by destination
// Get all available rates for a specific destination currency
const rates = await cray.fx.ratesByDestination({
    destination_currency: 'NGN'
});

// Generate a quote
// Lock in a rate for a conversion (valid for a limited time)
const quote = await cray.fx.quote({
    source_currency: 'NGN',
    destination_currency: 'USD',
    source_amount: 1500
});

// Execute conversion
// Finalize the conversion using the quote ID received from the quote step
const conversion = await cray.fx.convert({
    quote_id: 'quote:98a5d6d3-7cbc-4c7d-b4f6-d3bbbbe340b6'
});

// Query conversions history
// Get a list of past conversions
const history = await cray.fx.conversions();

5. Payouts

Manage disbursements and transfers.

// Get payment methods for a country
// Returns available payout methods (e.g., bank_transfer, mobile_money) for a specific country
const methods = await cray.payouts.paymentMethods('NG');

// Get banks (optionally filter by country code)
// Returns a list of supported banks and their codes
const banks = await cray.payouts.banks('GH');

// Validate account name
// Verify that an account number belongs to a specific user before disbursing
const account = await cray.payouts.validateAccount({
    account_number: '0112345678',
    bank_code: '058',
    country_code: 'GH' // if applicable
});

// Disburse funds
// Send money to a beneficiary
const transfer = await cray.payouts.disburse({
    customer_reference: 'ref-123',
    account_number: '898789',
    bank_code: '78978',
    amount: '10',
    currency: 'NGN',
    narration: 'Payment for services',
    sender_info: { name: 'My Business' },
    recipient_name: 'John Doe'
});

// Requery payout
// Check the status of a payout transaction
const status = await cray.payouts.requery('transaction_id');

6. Refunds

Initiate and track refunds.

// Initiate a refund (full or partial)
// 'pan': Masked PAN or token of the card to be refunded
// 'subaccount_id': The subaccount that received the original payment (if applicable)
const refund = await cray.refunds.initiate({
    pan: '4696660001638370',
    subaccount_id: '9999999999',
    amount: '1.2' // Optional, for partial refund
});

// Check refund status
const status = await cray.refunds.query('refund_reference_id');

7. Virtual Accounts

Create and manage NGN virtual collection accounts (Monnify, Wema, etc.).

// Create a virtual account
const va = await cray.virtualAccounts.create({
    bvn: '22192474887',
    type: 'Corporate',              // 'Corporate' or 'Individual'
    nin: '11111122221',
    virtual_account_type: 'Permanent', // 'Permanent' or 'Onetime'
    account_name: 'BOlaOla',
    rc_number: '99988828822',      // Required for Corporate type
    currency: 'NGN',
    reference: 'cbf0d060-1544-4a53-a00b-7cb75a3eb59d',
    customer_email: '[email protected]',
    provider: 'monnify',
});

// Initiate a virtual account request (pre-create step)
const initiated = await cray.virtualAccounts.initiate({
    provider: 'wema',
    bvn: '22192474887',
});

// List all virtual accounts for the merchant
const list = await cray.virtualAccounts.list();

// Get available virtual account providers
const providers = await cray.virtualAccounts.providers();

// Submit OTP to complete the two-step Wema flow
const result = await cray.virtualAccounts.submitOtp({
    merchant_id: '123',
    otp: '768238',
    customer_email: '[email protected]',
});

Error Handling

The package throws specific exceptions for different error scenarios.

import { 
    CrayAuthenticationException,
    CrayValidationException,
    CrayTimeoutException,
    CrayApiException 
} from "cray-node";

try {
    const response = await cray.cards.initiate(payload);
} catch (error) {
    if (error instanceof CrayAuthenticationException) {
        // Handle invalid API key or unauthorized access
    } else if (error instanceof CrayValidationException) {
        // Handle validation errors
        // error.errors contains details
    } else if (error instanceof CrayTimeoutException) {
        // Handle timeouts
    } else if (error instanceof CrayApiException) {
        // Handle other API errors
    }
}

License

The MIT License (MIT).