Refund via net settlement

Copy

This refund method applies to partners using the bulk settlement model, where Wise processes payouts ahead of receiving the settlement funds and reconciles via a daily settlement journal.

Under this model, Wise does not refund the sender directly. Instead, Wise notifies you that a transfer needs to be refunded, and you reimburse your customer. The refund amount is then accounted for in your next settlement cycle.

How it works

Refunds via net settlement can apply to both settled and unsettled transfers. Unsettled transfers that are refunded must still be included in the settlement journal.

When a refund is triggered, Wise:

1. Cancels the transfer.
2. Notifies you that the transfer needs to be refunded with a webhook event payload.
3. Moves the transfer status to funds_refunded.

You will then process the webhook event payload to refund your customer and reconcile via the settlement journal.

Refund webhook for net settlement

To use the webhook for net settlement refunds, Wise must first configure your integration to use the payout#create webhook event.

You can then:

1. Process the webhook payload.
2. Validate the webhook signature.
3. Refund your customer.
4. Reconcile via settlement.

Once configured, Wise sends notifications containing the refund data to your callback URL.

Your system should respond with an HTTP 200 to acknowledge successful receipt. You do not need to process the refund synchronously. You can batch refunds and process them later, but you must store the refund request and manage it internally from that point.

If Wise does not receive a 200 response (or the request times out), Wise will resend the notification for the same transfer ID. Your system must handle duplicate deliveries and not process the same refund twice.

Process the refund webhook payload

The webhook event data provides the details you need to apply the credit to the correct bank account or other payment mechanism, including:

• Amount
• Source currency
• Transfer ID

The payload for the payout#create notification includes the following fields:

Example payload:

{
  "event_type": "payout#create",
  "sent_at": "2025-10-14T12:43:37Z",
  "data": {
    "payoutId": 12345,
    "amount": 543.21,
    "currency": "EGP",
    "transferId": 98765,
    "customerTransactionId": "e592a7ba-d7d1-4c28-ac44-10cb091dad07"
  }
}

Validate webhook signature

Wise sends a signature header with each refund webhook request. You should validate this signature to confirm the request genuinely came from Wise.

Use the following public keys depending on your environment:

Refund your customer

Use the data.amount and data.currency fields from the payload to refund your customer via their original payment method (bank account, wallet, etc.).

Reconcile via settlement

Include refunded transfer IDs in the refundedTransfers array of your settlement journal. The refund amount is offset against your settlement — you pay Wise less (or nothing) for that settlement period.

When refunds exceed settlements

There may be occasions where the total refund amount for a settlement period exceeds the total amount to be settled with Wise. When this happens, the net amount is negative — meaning Wise owes you money.

When this occurs:

1. Record the amount owed by Wise in the settlement currency.
2. Offset it against future settlements using the balanceTransfer field in the Settlement Journal request request body.

Rules for balance transfer

• The maximum balanceTransfer per settlement is capped at the expected settlement amount before balance transfer is applied. The final settlement amount must be zero or positive. You cannot claim more than is owed in a single period.
• If the amount Wise owes you is larger than a single settlement, spread it across multiple settlements.
• Update your internal record of the amount owed by Wise each time you apply a balance transfer.

Calculation logic

balanceTransfer = min(amountOwedByWise, expectedSettlementAmount)
finalSettlementAmount = expectedSettlementAmount - balanceTransfer
amountOwedByWise = amountOwedByWise - balanceTransfer

Where:

• expectedSettlementAmount = total successful transfer payouts minus total refunds for the period.
• balanceTransfer = the portion of Wise's debt you are offsetting in this settlement.
• finalSettlementAmount = what you actually send to Wise (must be ≥ 0).