Issuing transaction/payment refunds

In this guide you will learn how to issue refunds using Qualy.

Before you start

You need to have a PaymentIntent _id, and Transaction _id of which you want to refund.

Use the PaymentIntent API to retrieve the PaymentIntent, once you retrieve the PaymentIntent, the property transactions will list all Transactions associated with the PaymentIntent, you will need the _id of Transaction you want to refund to proceed.

Creating a refund

To create a refund on Qualy, you will have to use the Transactions API.

When you create the refund Transaction, you can specify the total amount of the refund. The amount has to be negative and cannot be higher than the amount of the original Transaction which you will need to specifify in the ref property.

try {
  const response = await fetch('https://api.qualyhq.com/v1/transactions/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'ApiKey your-api-key-here',
      'X-TENANT-ID': 'your-tenant-id-here',
    },
    body: JSON.stringify({
      "amount": -150000,
      "currency": "AUD",
      "method": "ZAI_PAYID",
      "paymentIntent": "668b8dbec8fab6acd7b41cdd",
      "ref": "668bfc47f44334c60d96848e",
    }),
  });

  if (response.ok) {
    const data = await response.json();

    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}

The above request will return the following payload:

{
    "data": {
        "_id": "669a74931f74b42e14d633c2",
        "paymentIntent": "668b8dbec8fab6acd7b41cdd",
        "amount": -150000,
        "contact": "6606ab8ffb9085579f1b5844",
        "transactionType": "refund",
        "method": "ZAI_PAYID",
        "currency": "AUD",
        "documents": [],
        "status": "processing",
        "disputes": [],
        "ref": "668bfc47f44334c60d96848e",
        "createdAt": "2024-07-19T14:13:39.780Z",
        "number": 295
    }
}

You will receive updates on this refund via Webhooks. Refund transactions will have the transactionType set to refund instead of charge.

What's the workflow of a refund Transcation

Once a Transaction type refund is created, Qualy will attempt to direct debit the Bank Account of the the tenant for the amount specified and will automatically return to the contact using the same transaction method.

For example, if you are refunding a Credit Card (e.g. method ZAI_CC) transaction, the refund will be issued to the same credit card. If you are refunding the a PayID (e.g. method ZAI_PAYID) transaction, the refund will be issued to the same bank account as the original transaction. This behavior is essential to comply with the best practices and legistaltion on Anti-Money Laundering and Financing Terrorism.

Refunding "EXTERNAL" transactions

Qualy supports issuing refunds for transactions made outside of Qualy. When refunding this type of transaction, you will need to supply the bank account on which the funds should be disbursed, and the address of the student.

try {
  const response = await fetch('https://api.qualyhq.com/v1/transactions/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'ApiKey your-api-key-here',
      'X-TENANT-ID': 'your-tenant-id-here',
    },
    body: JSON.stringify({
      "amount": -150000,
      "currency": "AUD",
      "method": "EXTERNAL",
      "paymentIntent": "668b8dbec8fab6acd7b41cdd",
      "address":{
        "line1":"Line 1 of the address",
        "state":"Hauts-de-France",
        "postalCode": "00123",
        "country":"FR"
      },
      "bankAccount": "668b8dfec8fab6acd7b41cde"
      "ref": "668bfc47f44334c60d96848e",
    }),
  });

  if (response.ok) {
    const data = await response.json();

    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}