rapyd-client

Production-grade TypeScript SDK for the Rapyd fintech-as-a-service platform.

Features

• Full API surface — Collect, Disburse, Wallet, Issuing, Partner, Webhook, Resource
• 230+ service methods across 7 domain-aligned service classes
• HMAC-SHA256 request signing — every request automatically authenticated
• Webhook verification — constant-time timingSafeEqual HMAC, typed events, dispatch router
• Full-jitter exponential backoff — configurable maxRetries, retries only on 429/5xx
• Discriminated union results — Result<T> type, no surprise exceptions
• Structured errors — 18 semantic error.type values, retryable flag, operationId
• Dual ESM + CJS build — works in Node.js 18+, bundlers, and edge runtimes
• Zero runtime dependencies — only Node.js built-ins (crypto, fetch)
• Full TypeScript — strict mode, exact optional properties, exhaustive types

Installation

npm install rapyd-client

Requires Node.js ≥ 18 (for native fetch and crypto).

Quick Start

import { RapydClient } from "rapyd-client";

const rapyd-client = new RapydClient({
  accessKey: process.env.RAPYD_ACCESS_KEY!,
  secretKey:  process.env.RAPYD_SECRET_KEY!,
  sandbox:    true,
});

const result = await rapyd-client.collect.createPayment({
  amount:   100.00,
  currency: "USD",
  payment_method: {
    type:   "us_visa_card",
    fields: {
      number:           "4111111111111111",
      expiration_month: "12",
      expiration_year:  "2026",
      cvv:              "123",
    },
  },
});

if (result.ok) {
  console.log("Payment created:", result.data);
} else {
  console.error(`[${result.error.type}]`, result.error.message);
}

Configuration

const rapyd-client = new RapydClient({
  accessKey:        "your_access_key",  // required
  secretKey:        "your_secret_key",  // required
  sandbox:          true,               // default: true (false = production)
  maxRetries:       4,                  // default: 4 (1 = no retries)
  timeoutMs:        30_000,             // default: 30 000 ms
  merchantAccountId: "org_abc123",      // optional: Partner / PayFac scope
});

Services

Collect

// Payments
const r = await rapyd-client.collect.createPayment({ amount: 100, currency: "USD", ... });
const r = await rapyd-client.collect.getPayment("pay_id");
const r = await rapyd-client.collect.listPayments({ currency: "USD" });
const r = await rapyd-client.collect.capturePayment("pay_id");
const r = await rapyd-client.collect.cancelPayment("pay_id");
const r = await rapyd-client.collect.completePayment("token", "param3");

// Hosted checkout
const r = await rapyd-client.collect.createCheckoutPage({ amount: 100, currency: "USD" });

// Refunds
const r = await rapyd-client.collect.createRefund({ payment: "pay_id", amount: 25 });
const r = await rapyd-client.collect.cancelRefund("ref_id");

// Subscriptions
const r = await rapyd-client.collect.createPlan({ amount: 10, currency: "USD", interval: "month" });
const r = await rapyd-client.collect.createSubscription({ customer: "cus_id", plan: "plan_id" });
const r = await rapyd-client.collect.cancelSubscription("sub_id");

// Invoices
const r = await rapyd-client.collect.createInvoice({ customer: "cus_id", currency: "USD" });
const r = await rapyd-client.collect.finalizeInvoice("inv_id");
const r = await rapyd-client.collect.payInvoice("inv_id");

Disburse

const r = await rapyd-client.disburse.createBeneficiary({ category: "bank", country: "US", ... });
const r = await rapyd-client.disburse.createPayout({ payout_amount: 200, payout_currency: "EUR", ... });
const r = await rapyd-client.disburse.confirmPayout("payout_id");
const r = await rapyd-client.disburse.listPayoutMethodTypes({ sender_country: "US" });
const r = await rapyd-client.disburse.getPayoutRequiredFields(
  "us_ach_bank", "individual", "individual", "US", "USD"
);

Wallet

const r = await rapyd-client.wallet.createWallet({ type: "person", first_name: "Ada" });
const r = await rapyd-client.wallet.changeWalletStatus("ew_id", "disable");
const r = await rapyd-client.wallet.createContact("ew_id", { contact_type: "personal" });
const r = await rapyd-client.wallet.transferFunds({ source_ewallet: "ew_1", destination_ewallet: "ew_2", amount: 100, currency: "USD" });
const r = await rapyd-client.wallet.createVirtualAccount({ ewallet: "ew_id", country: "US" });
const r = await rapyd-client.wallet.createIdentityVerification({ ewallet: "ew_id", contact: "con_id" });

Issuing

const r = await rapyd-client.issuing.issueCard({ card_program: "cp_id", ewallet_contact: "con_id" });
const r = await rapyd-client.issuing.activateCard("card_id");
const r = await rapyd-client.issuing.blockCard("card_id");
const r = await rapyd-client.issuing.getCardDetails("card_id");   // PCI scope — returns PAN + CVV
const r = await rapyd-client.issuing.provisionGooglePay("card_id", { device_id: "dev_id" });
const r = await rapyd-client.issuing.simulateCardAuth({ card: "card_id", amount: 25 });

Partner

const r = await rapyd-client.partner.createOrganization({ name: "Acme Inc", country: "US" });
const r = await rapyd-client.partner.createApplication({ ewallet: "ew_id", type: "merchant" });
const r = await rapyd-client.partner.submitApplication("app_id");
const r = await rapyd-client.partner.approveApplication("app_id");
const r = await rapyd-client.partner.createSettlementBankAccount({ account_number: "123", currency: "USD", country: "US" });

Webhook Handling

Always verify the signature before trusting event data:

import express from "express";
import { RapydClient } from "rapyd-client";
import type { WebhookEvent } from "rapyd-client";

const rapyd-client = new RapydClient({ accessKey: "...", secretKey: "..." });

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const result = rapyd-client.webhook.parseAndVerify(req.body.toString(), {
    salt:      req.headers["salt"]      as string,
    timestamp: req.headers["timestamp"] as string,
    signature: req.headers["signature"] as string,
  });

  if (!result.ok) {
    res.sendStatus(401);
    return;
  }

  rapyd-client.webhook.dispatch(result.data, {
    "PAYMENT_SUCCEEDED": handlePayment,
    "PAYOUT_COMPLETED":  handlePayout,
    "default":           (e: WebhookEvent) => console.log("unhandled event", e.type),
  });

  res.sendStatus(200);
});

Error Handling

All service methods return Promise<Result<unknown>> — a discriminated union that never throws:

const result = await rapyd-client.collect.createPayment(params);

if (result.ok) {
  // result.data is the Rapyd "data" field from the response envelope
  const payment = result.data as Payment;
  console.log(payment.id, payment.status);
} else {
  const { type, message, errorCode, statusCode, operationId, retryable } = result.error;

  switch (type) {
    case "insufficient_funds":
      return promptAnotherPaymentMethod();
    case "rate_limit":
      if (retryable) return retry();
      break;
    case "unauthorized":
      throw new Error("Invalid Rapyd credentials");
    default:
      logger.error("Rapyd error", { type, errorCode, statusCode, operationId });
  }
}

Error types

| type | HTTP | retryable | |---|---|---| | payment_not_found | 404 | ✗ | | payment_failed | 400 | ✗ | | payment_canceled | 400 | ✗ | | insufficient_funds | 400 | ✗ | | card_declined | 400 | ✗ | | expired_card | 400 | ✗ | | invalid_card | 400 | ✗ | | do_not_honor | 400 | ✗ | | fraud | 400 | ✗ | | rate_limit | 429 | ✓ | | unauthorized | 401 | ✗ | | forbidden | 403 | ✗ | | not_found | 404 | ✗ | | validation | — | ✗ | | webhook_signature | — | ✗ | | network | — | ✓ | | timeout | — | ✓ | | api_error / unknown | 5xx | ✓ |

Testing

Services accept a RequestFn — swap it in tests without any network:

import { CollectService } from "rapyd-client";
import type { RequestFn } from "rapyd-client";

const mockRequest: RequestFn = async (method, path, body) => ({
  ok: true,
  data: { id: "pay_test", status: "ACT" },
});

const svc = new CollectService(mockRequest);
const result = await svc.createPayment({ amount: 100, currency: "USD" });
// result.ok === true, result.data.id === "pay_test"

For full HTTP-level tests the package uses MSW to intercept fetch without a real server.

License

MIT — see LICENSE.