Cashramp SDK

The official NodeJS SDK for Cashramp's API.

Table of Contents

• Installation
• Quick Start
• Usage Examples
  • Hosted Payments
  • Direct Ramp - Deposits
  • Direct Ramp - Withdrawals
• API Reference
  • Queries
  • Mutations
• Custom Queries
• Error Handling
• TypeScript Support

Installation

# NPM
npm install cashramp --save

# Yarn
yarn add cashramp

Quick Start

// CommonJS
const Cashramp = require("cashramp");

// ES6 import
import Cashramp from "cashramp";

const cashramp = new Cashramp({
  env: "test", // "test" for sandbox, "live" for production
  secretKey: "CSHRMP-SECK_your_secret_key",
});

Usage Examples

Hosted Payments

Hosted payments redirect users to Cashramp's hosted page to complete transactions.

// Initiate a hosted deposit (user pays fiat, you receive crypto)
const deposit = await cashramp.initiateHostedPayment({
  amount: 100,
  currency: "usd", // "usd" or "local_currency"
  countryCode: "GH",
  paymentType: "deposit",
  reference: "order_123",
  firstName: "John",
  lastName: "Doe",
  email: "[email protected]",
  redirectUrl: "https://yoursite.com/callback",
});

if (deposit.success) {
  // Redirect user to hosted page
  console.log(deposit.result.hostedLink);
}

Direct Ramp - Deposits

Direct Ramp gives you full control over the payment UI. Users pay fiat and receive stablecoins.

// Step 1: Create a customer
const customer = await cashramp.createCustomer({
  firstName: "John",
  lastName: "Doe",
  email: "[email protected]",
  country: "country_global_id", // from getAvailableCountries()
});

// Step 2: Get a quote
const quote = await cashramp.getRampQuote({
  customer: customer.result.id,
  amount: 100,
  currency: "usd",
  paymentType: "deposit",
  paymentMethodType: "mobile_money", // from getPaymentMethodTypes()
});

// Step 3: Initiate the deposit
const deposit = await cashramp.initiateRampQuoteDeposit({
  rampQuote: quote.result.id,
  reference: "order_123",
  phoneNumber: "+233123456789", // for mobile money
});

if (deposit.success) {
  console.log(deposit.result.paymentDetails); // Show payment instructions to user
  console.log(deposit.result.expiresAt); // Payment deadline
}

// Step 4: Mark as paid (after user confirms payment)
await cashramp.markDepositAsPaid({
  paymentRequest: deposit.result.id,
  receipt: "optional_payment_receipt_url",
});

Receiving Stablecoins Onchain

To deliver stablecoins directly to a wallet address instead of your Cashramp Merchant Dashboard balance:

const deposit = await cashramp.initiateRampQuoteDeposit({
  rampQuote: quote.result.id,
  reference: "order_123",
  onchainTransferInfo: {
    address: "0x1234567890abcdef1234567890abcdef12345678",
    cryptocurrency: "usd_tether", // from getRampableAssets()
    network: "celo", // from getRampableAssets()
  },
});

Direct Ramp - Withdrawals

Users receive fiat to their bank/mobile money from stablecoins.

// Step 1: Create customer (if not exists)
const customer = await cashramp.createCustomer({
  firstName: "John",
  lastName: "Doe",
  email: "[email protected]",
  country: "country_global_id",
});

// Step 2: Add a payment method for the customer
const paymentMethod = await cashramp.addPaymentMethod({
  customer: customer.result.id,
  paymentMethodType: "bank_transfer",
  fields: [
    { identifier: "account_number", value: "1234567890" },
    { identifier: "bank_name", value: "Example Bank" },
  ],
});

// Step 3: Get a quote
const quote = await cashramp.getRampQuote({
  customer: customer.result.id,
  amount: 50,
  currency: "usd",
  paymentType: "withdrawal",
  paymentMethodType: "bank_transfer",
});

// Step 4: Initiate withdrawal
const withdrawal = await cashramp.initiateRampQuoteWithdrawal({
  rampQuote: quote.result.id,
  paymentMethod: paymentMethod.result.id,
  reference: "withdrawal_456",
});

// Step 5: Mark as received (after user confirms receipt)
await cashramp.markWithdrawalAsReceived({
  paymentRequest: withdrawal.result.id,
});

API Reference

Queries

| Method | Parameters | Description | | ------------------------------------------ | ------------------------------------------------------ | -------------------------------------------------- | | getAvailableCountries() | - | Fetch countries where Cashramp operates | | getMarketRate({ countryCode }) | countryCode: ISO 3166-1 code (e.g., "GH", "NG") | Get current deposit/withdrawal rates | | getPaymentMethodTypes({ country }) | country: Country global ID | Get available payment methods (bank, mobile money) | | getRampableAssets() | - | Get supported cryptocurrencies and networks | | getRampLimits() | - | Get min/max transaction limits | | getRampQuote({ ... }) | See below | Request a quote for Direct Ramp | | refreshRampQuote({ rampQuote, amount? }) | rampQuote: Quote ID, amount: New amount (optional) | Refresh an existing quote | | getPaymentRequest({ reference }) | reference: Your reference string | Fetch payment request details | | getAccount() | - | Get your account balance and deposit address |

getRampQuote Parameters

| Parameter | Type | Required | Description | | ------------------- | ------ | -------- | ----------------------------- | | customer | string | Yes | Customer's global ID | | amount | number | Yes | Amount to ramp | | currency | string | Yes | "usd" or "local_currency" | | paymentType | string | Yes | "deposit" or "withdrawal" | | paymentMethodType | string | Yes | Payment method identifier | | country | string | No | ISO 3166-1 country code |

Mutations

Hosted Payments

| Method | Description | | ----------------------------------------- | ------------------------------ | | initiateHostedPayment({ ... }) | Start a hosted payment session | | cancelHostedPayment({ paymentRequest }) | Cancel a hosted payment |

Customer Management

| Method | Description | | ----------------------------------------------------------- | ------------------------------ | | createCustomer({ firstName, lastName, email, country }) | Create a new customer | | addPaymentMethod({ customer, paymentMethodType, fields }) | Add payment method to customer |

Direct Ramp - Deposits

| Method | Description | | ------------------------------------------------------------------------------------------------------------- | -------------------------- | | initiateRampQuoteDeposit({ rampQuote, reference?, phoneNumber?, bankAccountNumber?, onchainTransferInfo? }) | Start a deposit from quote | | markDepositAsPaid({ paymentRequest, receipt }) | Confirm user has paid | | cancelDeposit({ paymentRequest }) | Cancel a deposit |

Direct Ramp - Withdrawals

| Method | Description | | ----------------------------------------------------------------------- | ----------------------------- | | initiateRampQuoteWithdrawal({ rampQuote, paymentMethod, reference? }) | Start a withdrawal from quote | | markWithdrawalAsReceived({ paymentRequest }) | Confirm user received funds |

Other

| Method | Description | | --------------------------------------------------------- | --------------------------------- | | confirmTransaction({ paymentRequest, transactionHash }) | Confirm crypto transfer to escrow | | withdrawOnchain({ address, amountUsd }) | Withdraw from balance to wallet |

onchainTransferInfo Object

Used in initiateRampQuoteDeposit to deliver stablecoins onchain:

| Field | Type | Description | | ---------------- | ------ | ------------------------------------- | | address | string | Destination wallet address | | cryptocurrency | string | e.g., "usd_tether", "usd_coin" | | network | string | e.g., "celo", "polygon", "base" |

Custom Queries

For advanced use cases, use sendRequest to execute custom GraphQL queries:

const query = `
  query {
    availableCountries {
      id
      name
      code
      currency {
        isoCode
        name
      }
    }
  }
`;

const response = await cashramp.sendRequest({
  name: "availableCountries",
  query,
});

if (response.success) {
  console.log(response.result);
}

Error Handling

All methods return a consistent response object:

// Success response
{
  success: true,
  result: { /* response data */ }
}

// Error response
{
  success: false,
  error: "Error message describing what went wrong"
}

Always check success before accessing result:

const response = await cashramp.getMarketRate({ countryCode: "GH" });

if (response.success) {
  console.log(`Deposit rate: ${response.result.depositRate}`);
  console.log(`Withdrawal rate: ${response.result.withdrawalRate}`);
} else {
  console.error(`Error: ${response.error}`);
}

TypeScript Support

This SDK includes TypeScript definitions out of the box. No additional @types package needed.

Documentation

For detailed API documentation and webhook integration, visit Cashramp's API docs.