Refunds and returns

This page covers two different ways money comes back: a refund, which you start through the API, and a return, which a bank sends back on its own. In V1, refunds went through Wingspan support. In V3 you can issue most refunds yourself.

Refund a payable

Call POST /v3/payments/payables/{payableId}/refund on a payable that has been paid and deposited. Omit amount to refund the remaining refundable balance, or send an amount for a partial refund.

curl -X POST "https://api.wingspan.app/v3/payments/payables/Hb4Xk9Qw2Rt7Vn1Mz8Pc3L/refund" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Idempotency-Key: nw-refund-NW-AP-20431-1" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 184.00, "reason": "Overbilled 4 hours" }'

// (trimmed)
{
  "id": "Hb4Xk9Qw2Rt7Vn1Mz8Pc3L",
  "status": "PartiallyRefunded",
  "amount": 1840.00,
  "refunds": [
    { "id": "It3Lx9Qv6Wz2Kn8Rt1Mb5P", "amount": 184.00, "currency": "USD", "status": "Pending", "reason": "Overbilled 4 hours" }
  ],
  "events": { "paidAt": "2026-09-24T15:06:05Z", "refundedAt": "2026-10-01T13:20:44Z" }
}

The payable moves to Refunded or PartiallyRefunded, and the refund appears in refunds[] with its own status: Pending, Processing, Completed, Failed, or Cancelled.
reason is kept for your records and is shown only to your Account.
Always send an Idempotency-Key. Refunds move money, and a retry with the same key returns the original result instead of refunding twice.
Refunding is a high-risk action. Without recent multi-factor authentication it returns 403 with code: StepUpMfaRequired.
Once a refund settles, amountDetails.refunds reflects it.

You can't refund through the API when the payment was routed to a card, when the payable was paid off-platform, or when you need to target one specific payment on a payable that has several. For those, and for anything you're unsure about, contact Wingspan support at [email protected] with the payable's id and invoiceNumber.

Refund webhooks aren't subscribable yet. Read the payable to follow a refund's status.

Returns

A return happens when a bank sends a payment back after Wingspan sent it, for example because the receiving account is closed or the details are wrong. You don't start a return; you react to one.

A payout to a payee is returned

The payable moves to Returned and the Payable.Returned webhook fires. The affected leg shows status: Returned in payments[] (the collection from you) or payouts[] (the payout to the payee). A returned or failed collection attempt carries a statusReason, such as AccountNotFound or InsufficientFunds.

Returned is terminal for that payable. You can't retry it or change its funding source. To pay the payee again:

Fix the cause with the payee, usually their payout method. See Payout methods.
Create a new payable for the same amount. Use a new externalId, or add a suffix to your original, so it doesn't collide with the returned one.
Open, approve, and pay it. See Create a payable.

A payable that's still in progress when something goes wrong, rather than cleanly returned, needs a Wingspan operator to review it. Contact support if a payable stays in PaymentInTransit longer than you expect.

Your payroll funding debit is returned

If your bank returns the debit that funded a payroll run, the run moves to Failed with failureReason.code: FundingDebitReturned. This is the one failure where your money actually moved, so reprocessing goes through Wingspan support. See Payroll runs.

Paid isn't final

Paid is Wingspan's internal state. DepositConfirmed means Wingspan's originating bank or provider reported its terminal processed state. It never means the recipient's bank received the money, funds are available, or the payment can't be returned. A payable can move to Returned after both. See Paid vs DepositConfirmed.

Reconciling refunds and returns

Subscribe to Payable.Paid and Payable.Returned, and dedupe on the event id. If your endpoint was down, recover missed events from the event log. See Recover missed events.
Match Wingspan payables to your books with externalId. Keep the returned payable and its replacement linked in your system, for example with a shared metadata key.
Read amountDetails for the settled breakdown: paid, fees, deductions, payouts, and refunds. It's omitted until settled activity is complete, and returned activity doesn't count toward it.