# Issuing transaction/payment refunds

> Learn how Qualy can issue refunds to payments.

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](https://v1-spec.qualyhq.com/#get-/v1/payment-intents) 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](https://v1-spec.qualyhq.com/#post-/v1/transactions/create).

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.

**cURL**

```bash
curl -X POST https://api.qualyhq.com/v1/transactions/create \
  -H 'Authorization: ApiKey your-api-key-here' \
  -H 'X-TENANT-ID: your-tenant-id-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": -150000,
    "currency": "AUD",
    "method": "ZAI_PAYID",
    "paymentIntent": "668b8dbec8fab6acd7b41cdd",
    "ref": "668bfc47f44334c60d96848e"
  }'
```

**JavaScript**

```javascript
const res = 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, // negative: a refund
    currency: 'AUD',
    method: 'ZAI_PAYID',
    paymentIntent: '668b8dbec8fab6acd7b41cdd',
    ref: '668bfc47f44334c60d96848e', // the original transaction _id
  }),
});

const { data: refund } = await res.json();
console.log(refund._id, refund.transactionType); // "…" "refund"
```

**PHP (Laravel)**

```php
use Illuminate\Support\Facades\Http;

$refund = Http::withHeaders([
    'Authorization' => 'ApiKey your-api-key-here',
    'X-TENANT-ID' => 'your-tenant-id-here',
])->post('https://api.qualyhq.com/v1/transactions/create', [
    'amount' => -150000, // negative: a refund
    'currency' => 'AUD',
    'method' => 'ZAI_PAYID',
    'paymentIntent' => '668b8dbec8fab6acd7b41cdd',
    'ref' => '668bfc47f44334c60d96848e', // the original transaction _id
])->json('data');

echo $refund['_id'] . ' ' . $refund['transactionType'];
```

The above request will return the following payload:

```json
{
    "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](/docs/webhooks.md). 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](https://v1-spec.qualyhq.com/#post-/v1/bank-accounts/create) 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.

**cURL**

```bash
curl -X POST https://api.qualyhq.com/v1/transactions/create \
  -H 'Authorization: ApiKey your-api-key-here' \
  -H 'X-TENANT-ID: your-tenant-id-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "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"
  }'
```

**JavaScript**

```javascript
const res = 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',
  }),
});

const { data: refund } = await res.json();
console.log(refund._id);
```

**PHP (Laravel)**

```php
use Illuminate\Support\Facades\Http;

$refund = Http::withHeaders([
    'Authorization' => 'ApiKey your-api-key-here',
    'X-TENANT-ID' => 'your-tenant-id-here',
])->post('https://api.qualyhq.com/v1/transactions/create', [
    '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',
])->json('data');

echo $refund['_id'];
```