Recipes: Transfers & refunds

Send a transfer with idempotent retries

Handle transient failures without accidentally double-sending.

import { Sly } from '@sly_ai/sdk';
const sly = new Sly({ apiKey: process.env.SLY_API_KEY });

async function sendWithRetries(opts, maxAttempts = 3) {
  const idempotencyKey = opts.idempotencyKey ?? `tx-${opts.orderId}`;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await sly.transfers.create({ ...opts, idempotencyKey });
    } catch (e) {
      if (attempt === maxAttempts) throw e;
      if (!['UPSTREAM_TIMEOUT', 'RATE_LIMIT_EXCEEDED', 'INTERNAL_ERROR'].includes(e.code)) throw e;
      await new Promise(r => setTimeout(r, 500 * 2 ** attempt));
    }
  }
}

const result = await sendWithRetries({
  type: 'internal',
  from_wallet_id: 'wal_src',
  to_wallet_id: 'wal_dst',
  amount: '100.00',
  currency: 'USDC',
  orderId: 'ord_abc',
});

# Same idempotency key on every retry — server returns cached result
KEY="tx-ord_abc-$(date +%Y%m%d)"

for attempt in 1 2 3; do
  RESP=$(curl -s -o /tmp/resp.json -w "%{http_code}" \
    -X POST https://api.getsly.ai/v1/transfers \
    -H "Authorization: Bearer $SLY_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"type\":\"internal\",\"from_wallet_id\":\"wal_src\",\"to_wallet_id\":\"wal_dst\",\"amount\":\"100.00\",\"currency\":\"USDC\",\"idempotency_key\":\"$KEY\"}")
  [ "$RESP" = "200" ] || [ "$RESP" = "201" ] && break
  sleep $((attempt * 2))
done
cat /tmp/resp.json

Wait for a transfer to settle

const final = await sly.transfers.waitForSettlement(transfer.id, { timeout: 60_000 });
if (final.status === 'completed') {
  // done
} else {
  console.error('Settlement failed:', final.failure_reason);
}

// server.ts
app.post('/webhooks/sly', express.raw({ type: '*/*' }), (req, res) => {
  const event = verifyWebhook(req.body, req.headers['x-sly-signature'], process.env.WEBHOOK_SECRET);
  if (event.type === 'transfer.completed') {
    markOrderPaid(event.data.transfer_id);
  }
  res.status(200).end();
});

Polling is simpler; webhooks scale. Use webhooks past the prototype stage.

Batch payroll (100+ transfers)

const payroll = await sly.transfers.createBatch({
  transfers: contractors.map(c => ({
    to_account_id: c.sly_account_id,
    amount: c.pay_usdc,
    currency: 'USDC',
    memo: `Payroll ${period}`,
    idempotency_key: `payroll-${period}-${c.id}`,
  })),
  idempotency_key: `payroll-batch-${period}`,
});

// Subscribe to batch.completed for final totals

The batch returns a batch_id; individual items each settle independently. Partial failures don’t sink the whole batch.

Full refund with audit trail

const refund = await sly.refunds.create({
  originalTransferId: 'tx_...',
  reason: 'customer_request',
  reasonDetails: 'Customer emailed 2026-04-23 requesting full refund',
  // omit amount = full refund
}, { idempotencyKey: `refund-${originalId}` });

console.log(refund.status);   // 'pending' → 'completed'

Always include reasonDetails — it becomes your dispute defense if the buyer chargebacks later.

Partial refund with running total

Multiple partial refunds per transfer are allowed as long as the cumulative total stays ≤ the original amount:

// First partial: $30 of $100
await sly.refunds.create({
  originalTransferId: 'tx_abc',
  amount: '30.00',
  reason: 'service_not_rendered',
  reasonDetails: 'Partial delivery — 3 of 10 items',
});

// Later: additional $20
await sly.refunds.create({
  originalTransferId: 'tx_abc',
  amount: '20.00',
  reason: 'customer_request',
});

// Would fail: $100 + $30 + $20 = exceeds original
// await sly.refunds.create({ originalTransferId: 'tx_abc', amount: '55.00', ... });

Export transfers to CSV

Dashboard has a one-click export; the programmatic path:

curl -X POST https://api.getsly.ai/v1/exports \
  -H "Authorization: Bearer pk_live_..." \
  -d '{
    "resource": "transfers",
    "format": "csv",
    "filters": {
      "status": "completed",
      "since": "2026-04-01",
      "until": "2026-04-30"
    }
  }'
# Response: { "export_id": "exp_...", "status": "pending" }

# Poll
curl https://api.getsly.ai/v1/exports/exp_... \
  -H "Authorization: Bearer pk_live_..."
# When status = 'ready', fetch `download_url`

For ad-hoc exports < 10k rows, the dashboard’s CSV download is faster. API exports win past that scale.

Schedule a recurring transfer

Monthly payroll on the 1st at 9am ET:

const schedule = await sly.scheduledTransfers.create({
  fromAccountId: 'acc_treasury',
  toAccountId: 'acc_payroll_dest',
  amount: '2500.00',
  currency: 'USDC',
  frequency: 'monthly',
  dayOfMonth: 1,
  timezone: 'America/New_York',
  startDate: '2026-05-01T09:00:00-04:00',
  retryEnabled: true,
});

See scheduled transfers for full frequency options.

Watch for stuck transfers

const stuck = await sly.transfers.list({
  status: 'processing',
  updated_before: new Date(Date.now() - 10 * 60_000).toISOString(), // > 10 min
});

if (stuck.data.length > 0) {
  await pageOps(stuck.data);
}

Run this in a cron or cron-equivalent (Vercel Cron, GitHub Actions) every 5-10 min. Stuck transfers past their typical settlement window usually indicate rail issues.

Get Started

Onboarding

Migration

Authentication

Core Concepts

Guides

Recipes

Architecture

Settlement & Treasury

Stellar

Protocols

Agent Platform

SDKs & Tools

Webhooks

Resources

Recipes: Transfers & refunds

Send a transfer with idempotent retries

Wait for a transfer to settle

Batch payroll (100+ transfers)

Full refund with audit trail

Partial refund with running total

Export transfers to CSV

Schedule a recurring transfer

Watch for stuck transfers

See also

​Send a transfer with idempotent retries

​Wait for a transfer to settle

​Batch payroll (100+ transfers)

​Full refund with audit trail

​Partial refund with running total

​Export transfers to CSV

​Schedule a recurring transfer

​Watch for stuck transfers

​See also

Send a transfer with idempotent retries

Wait for a transfer to settle

Batch payroll (100+ transfers)

Full refund with audit trail

Partial refund with running total

Export transfers to CSV

Schedule a recurring transfer

Watch for stuck transfers

See also