Balance Withdrawal

Authorization: Bearer YOUR_API_KEY

curl -X POST 'https://api-sandbox.paywithsoap.com/api/v1/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
    "customer_id": "cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870",
    "type": "withdrawal",
    "balance_amount_cents": 10000,
    "experience": "web",
    "return_url": "https://myapp.com/wallet"
}'

const express = require('express');
const app = express();

// Use a real database, not in-memory collections, to persist these across
// restarts.
const processedEventIds = new Set();

// checkoutId -> { customerId, amountCents }
// Withdrawals you have debited and not yet credited back. Store the amount
// yourself: checkout.expired arrives with no charge object, so the event
// cannot tell you how much to return.
const debitedWithdrawals = new Map();

// Credits back at most once per checkout, whichever event gets here first.
function creditBackHold(checkoutId) {
  const debit = debitedWithdrawals.get(checkoutId);
  if (!debit) return; // never debited for this checkout — nothing to undo
  creditLedger(debit.customerId, debit.amountCents);
  debitedWithdrawals.delete(checkoutId);
}

app.post('/webhooks/soap', express.raw({ type: 'application/json' }), (req, res) => {
  const event = JSON.parse(req.body.toString('utf8'));

  // event_id is your idempotency key — never apply the same event twice.
  if (processedEventIds.has(event.event_id)) {
    return res.sendStatus(200);
  }

  switch (event.type) {
    case 'checkout.hold': {
      const { id: checkoutId, charge, customer } = event.data;
      const hasSufficientFunds = getLedgerBalance(customer.id) >= charge.amount_cents;

      if (!hasSufficientFunds) {
        processedEventIds.add(event.event_id);
        return res.sendStatus(402); // non-2xx: withdrawal does not proceed
      }

      // Debit now, on the hold — this is what stops the customer from
      // spending these funds again before the withdrawal settles.
      debitLedger(customer.id, charge.amount_cents);
      debitedWithdrawals.set(checkoutId, {
        customerId: customer.id,
        amountCents: charge.amount_cents,
      });
      processedEventIds.add(event.event_id);
      return res.sendStatus(200); // 2xx: withdrawal proceeds
    }

    case 'checkout.succeeded': {
      const { id: checkoutId, type } = event.data;

      if (type === 'withdrawal' && debitedWithdrawals.has(checkoutId)) {
        // Already debited on checkout.hold. Debiting again here would be
        // the double-debit trap — this must be a no-op. The record stays so
        // a later reversal can still find the amount.
        processedEventIds.add(event.event_id);
        return res.sendStatus(200);
      }

      // Deposits (and any withdrawal you didn't debit on hold) settle here.
      applyLedgerUpdateForSucceededCheckout(event.data);
      processedEventIds.add(event.event_id);
      return res.sendStatus(200);
    }

    // Always delivered: the charge went straight from held to failed.
    case 'checkout.release_hold':
    // Off by default, and the one that actually strands money. An accepted
    // payout that fails later goes held -> pending -> failed, so Soap sends
    // this instead of release_hold. Also covers a settled payout bouncing,
    // where charge.from_status is "succeeded".
    case 'checkout.failed':
    // Always delivered. A completed payout was returned by the bank.
    case 'checkout.returned':
    // Off by default. Carries no charge object, which is why the amount
    // comes from your own record rather than the payload.
    case 'checkout.expired': {
      creditBackHold(event.data.id);
      processedEventIds.add(event.event_id);
      return res.sendStatus(200);
    }

    default:
      processedEventIds.add(event.event_id);
      return res.sendStatus(200);
  }
});