Implementation guides

Issuing refunds

Refunds in Qualy are refund intents. A refund intent says which payments you're refunding, how much, and where the money goes. Qualy works out fees, tax and FX, sends it for approval if your account requires it, funds it, and pays it out.

The flow is always the same:

  1. Get the options for the transaction you're refunding.
  2. Preview the refund to see what the payer will actually receive.
  3. Create the refund intent.
  4. Track it until it's completed.

Before you start

You need the _id of the transaction you're refunding (the charge), not just the payment. Get it from the payment's transactions:

const res = await fetch('https://api.qualyhq.com/v1/payment-intents/668b8dbec8fab6acd7b41cdd', {
  headers: {
    'Authorization': 'ApiKey your-api-key-here',
    'X-TENANT-ID': 'your-tenant-id-here',
  },
});

const { data: payment } = await res.json();
const charge = payment.transactions.find((t) => t.transactionType === 'charge');

Step 1: Get the refund options

GET /v1/refund-intents/options/{transactionId}/{settlementCurrency} lists the ways this charge can be refunded into a currency. Pass the charge's own currency for a same-currency refund, or another currency to refund cross-currency.

const res = await fetch(
  `https://api.qualyhq.com/v1/refund-intents/options/${charge._id}/AUD`,
  {
    headers: {
      'Authorization': 'ApiKey your-api-key-here',
      'X-TENANT-ID': 'your-tenant-id-here',
    },
  },
);

const { data } = await res.json();
// data.options – where the refund can go
// data.funding – how you can fund it

Each entry in options is a route you can use:

FieldDescription
method / gatewayThe method that will execute the refund.
kindnative-reverse (back to the original card or account), contact-bank (to a bank account you nominate) or supplier-payout (to the supplier, not the payer).
status / statusReasonOnly active options can be used. statusReason says why one isn't (an open dispute, another refund already in progress…).
maxAmountWhat's still refundable on this charge, in minor units.
requiredFieldsWhat you must send for this route, e.g. bankAccount.
settlementCurrencies / etaCurrencies the route can pay out in, and how long it usually takes.

Refunds go back where the money came from

For most methods the refund returns to the same card or account the payer used (native-reverse). This is an anti-money-laundering requirement, not a preference. Payments recorded outside Qualy (EXTERNAL) have no original instrument, so they refund to a bank account (contact-bank).


Step 2: Preview the refund

POST /v1/refund-intents/preview takes exactly the body you'll create with and returns the outcome, without saving anything:

const refund = {
  currency: 'AUD',
  route: {
    method: 'ZAI_PAYID',
    kind: 'native-reverse',
    source: 'tenant',
    destination: 'contact',
    settlementCurrency: 'AUD',
  },
  items: [
    {
      appliesTo: charge._id,
      grossAmount: 150000, // minor units
      basisCurrency: 'AUD',
    },
  ],
  refundReason: 'Visa refused',
  description: {
    external: 'Refund of your tuition deposit',
  },
};

const res = await fetch('https://api.qualyhq.com/v1/refund-intents/preview', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'ApiKey your-api-key-here',
    'X-TENANT-ID': 'your-tenant-id-here',
  },
  body: JSON.stringify(refund),
});

const { data: preview } = await res.json();
if (!preview.valid) console.log(preview.reasons); // [{ code, message }]
FieldDescription
valid / reasonsWhether the refund can be created as it is, and why not.
bundleGross / bundleNetTotal drawn from the charges, and what the payer receives after fees and tax.
items[]Per charge: feeRetained, taxTotal, refundableNet, settlementAmount and remainingAfter.
crossCurrency / fxRateSet when the refund pays out in a different currency.
qualyFeeEstimate / markupEstimateEstimated Qualy fee and FX markup on the refund.

Step 3: Create the refund intent

Send the same body to POST /v1/refund-intents/create:

curl -X POST https://api.qualyhq.com/v1/refund-intents/create \
  -H 'Authorization: ApiKey your-api-key-here' \
  -H 'X-TENANT-ID: your-tenant-id-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "currency": "AUD",
    "route": {
      "method": "ZAI_PAYID",
      "kind": "native-reverse",
      "source": "tenant",
      "destination": "contact",
      "settlementCurrency": "AUD"
    },
    "items": [
      { "appliesTo": "668bfc47f44334c60d96848e", "grossAmount": 150000, "basisCurrency": "AUD" }
    ],
    "refundReason": "Visa refused"
  }'

The request

FieldDescription
currencyThe basis currency of the refund (the charges' currency).
route.method, route.gatewayFrom the option you picked.
route.kindnative-reverse, contact-bank or supplier-payout.
route.sourceWho funds the refund: tenant (you) or supplier (you front it, and the supplier owes it back; see obligations).
route.destinationcontact (the payer) or supplier.
route.settlementCurrencyThe currency the refund is paid out in.
route.bankAccountRequired for contact-bank: the bank account to pay into.
route.partnershipRequired when the route involves a supplier.
items[]One per charge: appliesTo (the charge transaction), grossAmount (minor units) and basisCurrency. Optionally a fee to withhold ({ type: "percentage" | "fixed", value, appliedTo }) and taxes.
funding.methodpooled, per-item or balance. Leave it out and Qualy picks: usually pooled, one collection for the whole refund.
fxStrategyFor cross-currency refunds: re-quote-at-settlement or lock-and-absorb.
refundReason, description.internal, description.externalYour reason, an internal note, and the text the payer sees.

One refund intent can cover several charges, even across payments: add an item per charge.


Step 4: Track it

StatusMeaning
review-pendingWaiting for approval. See Approvals.
approvedApproved and waiting to be funded.
processingFunded and being paid out.
partially-completedSome items paid out, others still in progress or failed.
completedEvery item paid out.
failed / rejected / canceledStopped. A failed refund can be retried.

Read one with GET /v1/refund-intents/{id}, or list them with GET /v1/refund-intents (supports the usual query filters). As each item settles, Qualy records a transaction with transactionType: "refund" on the payment, so the transactions.create and paymentIntents.update webhooks fire as usual.

Managing a refund

EndpointUse it to…
POST /v1/refund-intents/{id}/cancelCancel a refund that hasn't been paid out yet.
POST /v1/refund-intents/{id}/retryRetry a failed refund.
POST /v1/refund-intents/{id}/abandon-fundingGive up on a refund still waiting for its funding to arrive.
POST /v1/refund-intents/{id}/receiptGet the refund receipt to share with the payer.
GET /v1/refund-intents/statsTotals for reporting.

When a supplier owes you

If the money you're refunding was already paid to a school or supplier, use route.source: "supplier" with its route.partnership. You still fund the payer's refund, and Qualy records an obligation: what the supplier owes you back.

  • GET /v1/refund-intents/obligations lists them.
  • POST /v1/refund-intents/obligations/{id}/settle marks one as settled.
  • GET /v1/refund-intents/obligations/{id}/receipt returns its receipt.

Refunding payments made outside Qualy

For a payment recorded with method EXTERNAL, use kind: "contact-bank" with the payer's bankAccount. Qualy executes the refund through a gateway enabled on your account for that currency.


Refund transactions (legacy)

Earlier integrations refunded by creating a negative transaction with POST /v1/transactions/create and ref set to the original charge. New integrations should use refund intents: they handle approvals, fees, tax, FX, partial and multi-payment refunds, and you can't create a refund transaction on a charge that already has a refund intent in progress.

Previous
Tax rates & calculation