Fund a wallet: Monierate

VOLUME_API_KEY=vk_test_...
VOLUME_WEBHOOK_SECRET=whsec_...

const VOLUME_API = 'https://api.paywithvolume.com';

/**
 * Calls the Volume API with your key. A refusal throws, carrying its `code`.
 * @param {string} path
 * @param {{ method?: string, body?: object, idempotencyKey?: string }} [options]
 */
export async function volume(path, { method = 'GET', body, idempotencyKey } = {}) {
  const response = await fetch(`${VOLUME_API}${path}`, {
    method,
    headers: {
      authorization: `Bearer ${process.env.VOLUME_API_KEY}`,
      ...(body ? { 'content-type': 'application/json' } : {}),
      ...(idempotencyKey ? { 'idempotency-key': idempotencyKey } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await response.json();
  if (!response.ok) {
    const error = new Error(json.error?.message ?? `Volume answered ${response.status}`);
    error.code = json.error?.code;
    error.requestId = json.error?.request_id;
    throw error;
  }
  return json;
}

/**
 * Opens a checkout for one top-up and returns where to send the user. `fundingId` is
 * your own record of the top-up: retrying with the same one never opens a second
 * invoice, because it makes the idempotency keys.
 */
export async function startFunding({ fundingId, email, amount }) {
  const invoice = await volume('/v1/invoices', {
    method: 'POST',
    idempotencyKey: `${fundingId}:invoice`,
    body: {
      amount, // a string such as "25.00", never a float
      description: 'Monierate wallet top-up',
      customer_email: email,
      metadata: { funding_id: fundingId },
    },
  });

  const checkout = await volume('/v1/checkout_sessions', {
    method: 'POST',
    idempotencyKey: `${fundingId}:checkout`,
    body: {
      invoice_id: invoice.id,
      success_url: `https://monierate.com/wallet?funding=${fundingId}`,
      cancel_url: 'https://monierate.com/wallet',
    },
  });

  return { invoiceId: invoice.id, checkoutSessionId: checkout.id, url: checkout.url };
}

import { randomUUID } from 'node:crypto';
import express from 'express';
import { startFunding } from './volume.js';
import { recordCheckout } from './wallet.js';

const app = express();

app.post('/wallet/fund', express.json(), async (req, res) => {
  const user = req.user; // however your app knows who is signed in
  const amount = String(req.body.amount); // after checking it against your minimum
  const fundingId = randomUUID(); // better: the id of a top-up record you saved first

  const { url, invoiceId, checkoutSessionId } = await startFunding({
    fundingId,
    email: user.email,
    amount,
  });
  await recordCheckout({ checkoutSessionId, invoiceId, userId: user.id });

  res.json({ url }); // the browser goes there next
});

import { owedCents } from './owed.js';
import { verifySignature } from './signature.js';

const CREDITING = new Set(['invoice.paid', 'invoice.overpaid', 'invoice.underpaid']);

/**
 * Handles one delivery and returns the HTTP status to answer with. `creditUpTo` is
 * yours: see "Credit the wallet once" below.
 */
export async function handleVolumeEvent({ rawBody, signature, secret, creditUpTo }) {
  if (!verifySignature(secret, rawBody, signature)) return 400;

  const event = JSON.parse(rawBody);
  if (CREDITING.has(event.type)) {
    const checkout = event.data.checkout_session;
    await creditUpTo(checkout.id, owedCents(checkout));
  }
  // Anything else (payment.confirmed, invoice.expired, a test event) needs nothing
  // here. Answer 2xx anyway, or Volume keeps retrying it.
  return 200;
}

import { handleVolumeEvent } from './webhook.js';
import { creditUpTo } from './wallet.js';

app.post('/webhooks/volume', express.raw({ type: 'application/json' }), async (req, res) => {
  const status = await handleVolumeEvent({
    rawBody: req.body.toString('utf8'),
    signature: req.get('Volume-Signature'),
    secret: process.env.VOLUME_WEBHOOK_SECRET,
    creditUpTo,
  });
  res.sendStatus(status);
});

/** A decimal string as an integer and its number of decimal places: "0.25" is 25n, 2. */
function decimal(text) {
  const match = /^(\d+)(?:\.(\d+))?$/.exec(text);
  if (!match) throw new Error(`Not a decimal: ${text}`);
  const fraction = match[2] ?? '';
  return [BigInt(match[1] + fraction), fraction.length];
}

/** `amount` coins at `rate` dollars per coin, in whole cents, rounded down. */
function cents(amount, rate) {
  const [units, places] = decimal(amount);
  const [price, rateScale] = decimal(rate);
  return (units * price * 100n) / 10n ** BigInt(places + rateScale);
}

const PAID = new Set(['paid', 'overpaid', 'settled']);

/**
 * What a checkout owes the wallet, in cents, from the `checkout_session` an event
 * carries: everything that has arrived, at the rate the payer was quoted, and never
 * less than the invoice once it is paid (Volume covers a small shortfall).
 */
export function owedCents(checkout) {
  const received = checkout.amount_received ? cents(checkout.amount_received, checkout.rate) : 0n;
  if (!PAID.has(checkout.status)) return received;
  const price = cents(checkout.amount_usd, '1');
  return received > price ? received : price;
}

CREATE TABLE volume_checkouts (
  checkout_session_id text   PRIMARY KEY,
  invoice_id          text   NOT NULL,
  user_id             text   NOT NULL,
  credited_cents      bigint NOT NULL DEFAULT 0
);

import pg from 'pg';

const db = new pg.Pool(); // reads the PG* environment variables

export async function recordCheckout({ checkoutSessionId, invoiceId, userId }) {
  await db.query(
    `INSERT INTO volume_checkouts (checkout_session_id, invoice_id, user_id)
     VALUES ($1, $2, $3) ON CONFLICT DO NOTHING`,
    [checkoutSessionId, invoiceId, userId],
  );
}

/** Raises what a checkout has credited to `owed` cents, crediting the difference. */
export async function creditUpTo(checkoutSessionId, owed) {
  const client = await db.connect();
  try {
    await client.query('BEGIN');
    const { rows } = await client.query(
      `SELECT user_id, credited_cents FROM volume_checkouts
        WHERE checkout_session_id = $1 FOR UPDATE`,
      [checkoutSessionId],
    );
    const row = rows[0];
    if (row && owed > BigInt(row.credited_cents)) {
      await client.query(
        'UPDATE volume_checkouts SET credited_cents = $2 WHERE checkout_session_id = $1',
        [checkoutSessionId, owed.toString()],
      );
      // Your wallet's own credit, in this same transaction:
      await creditWallet(client, row.user_id, owed - BigInt(row.credited_cents));
    }
    await client.query('COMMIT');
  } catch (error) {
    await client.query('ROLLBACK');
    throw error;
  } finally {
    client.release();
  }
}