# 1. Prepare a refund

**POST** `/payout/refund/direct/local`

Base URL: `https://api.triple-a.io/api/v2`

Initiate a refund in the cryptocurrency that was received by the payment.

**Note** : This provides a quote that expires 60 seconds after creation.

## Authorization

- bearer_auth (http, bearer)

## Body

Content type: `application/json`

- `payment_reference` (string, required)
  Unique Payment Reference Number to refund from
- `address` (string, required)
  Crypto address of the refund recipient. The receiving wallet address must be for the same cryptocurrency as the payment.
- `refund_amount` (number<float>, required)
  Amount of the payment to be refunded. The refund currency is the
  original payment currency
- `refund_reason` ("requested_by_customer" | "aml")
  String indicating the reason for the refund. The available options are `requested_by_customer` to signify a typical refund requested by the customer, and `aml` to indicate that you suspect the original payment may be associated with illegal activity. If `aml` is specified, there is a possibility that the user or wallet may be restricted from conducting any further transactions.
- `remarks` (string)
  Remarks for the payout
- `notify_url` (string<uri>)
  The URL to send the webhook notification. The webhook URL given
  in your account setup will be used if this is not provided.
  For testing you can use [webhook.site](https://webhook.site)
- `notify_secret` (string)
  The shared secret that will be used to sign the notification.
  This secret can be at most 64 characters long.
  If this is not provided in the payment request, the system will
  create a random secret just for that payment.

Example:

```json
{
  "payment_reference": "SDF-453672-PMT",
  "address": "mtzozh***************xZ18Ggc00hbf",
  "refund_amount": 12.75,
  "refund_reason": "requested_by_customer",
  "remarks": "Refund for a water pistol",
  "notify_url": "https://webhook.site/1a2d24e8-1594-4569-bc35-079049e4d805",
  "notify_secret": "Cf9mx4nAvRuy5vwBY2FCtaKr"
}
```

## Responses

### 200

Success

- `payout_reference` (string)
  Unique payout reference number
- `order_id` (string)
  Your system unique order id. You will get this in the notification webhook data, if you insert your unique order_id in the request body during the payout/settlement creation.
- `type` ("refund" | "withdraw")
  The type of payout:

  1. `refund` - A partial or complete refund of a prior successful
  payment.

  2. `withdraw` - A settlement of the merchant's accumulated USD
  balance in cryptocurrency.
- `account_type` ("local")
  Account type the funds are drawn from: `local` - Funds are drawn
  from a local currency account
- `convert_type` ("local-local" | "local-crypto")
  Type of conversion the funds underwent:

  1. `local-local` - Funds are drawn from a local currency account
  and paid out as local currency.

  2. `local-crypto` - Funds are drawn from a local currency account
  and paid out as cryptocurrency.
- `local_currency` (string)
  The local currency equivalent of the payout. This should be a
  [3-character ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
  currency code. Please ignore if the payout is in cryptocurrency.
- `local_amount` (number<float>)
  The local currency amount to be paid out. Please ignore if the
  payout is in cryptocurrency.
- `crypto_currency` (string)
  Cryptocurrency that will be paid out. Please ignore if the payout
  is in local currency.
- `crypto_amount` (number<float>)
  Amount of cryptocurrency to be paid out if the settlement is in
  cryptocurrency.
- `network_fee_crypto_amount` (number<float>)
  Amount of cryptocurrency representing the network fee. This is denominated in `crypto_currency`.
- `net_crypto_amount` (number<float>)
  Amount of cryptocurrency after deduction of the `network_fee_crypto_amount`.
- `crypto_address` (string)
  Address that recipient will receive the payout at.
- `exchange_rate` (number<float>)
  The exchange rate that will be used to exchange local currency to
  cryptocurrency or vice-versa.
- `status` ("new" | "confirm" | "done" | "cancel")
  The current status of the payout:

  1. `new` - The payout has just been created, but the recipient has not
  entered in their receiving crypto address and the exchange rate has
  not been fixed.

  2. `confirm` - The recipient has confirmed their receiving crypto
  address and the exchange rate has been fixed.

  3. `done` - The crypto payout has been broadcast to the blockchain.

  4. `cancel` - The crypto payout has been cancelled.

  5. `pending_authorization` - The crypto payout is pending for authorization.
- `status_date` (string<date-time>)
  Date and time the status was updated
- `merchant_name` (string)
  Name of the merchant
- `remarks` (string)
  Remarks for the payout
- `notify_url` (string<uri>)
  The URL to send the webhook notification. The webhook URL given
  in your account setup will be used if this is not provided.
  For testing you can use [webhook.site](https://webhook.site)
- `notify_secret` (string)
  The shared secret that will be used to sign the notification.
  This secret can be at most 64 characters long.
  If this is not provided in the payment request, the system will
  create a random secret just for that payment.

Example:

```json
{
  "payout_reference": "AGJ-937870-PYT",
  "order_id": "<your_order_id>",
  "type": "withdraw",
  "account_type": "local",
  "convert_type": "local-crypto",
  "local_currency": "SGD",
  "local_amount": 10,
  "crypto_currency": "testBTC",
  "crypto_amount": 0.001067203,
  "network_fee_crypto_amount": 0.000007203,
  "net_crypto_amount": 0.00106,
  "crypto_address": "1NcAyv8YVCnQGCrDb4kiUm1jj6GLyowxER",
  "exchange_rate": 10277.49,
  "status": "new",
  "status_date": "2020-01-26T03:57:22Z",
  "merchant_name": "A to Z Toys and Games",
  "remarks": "Refund for a water pistol",
  "notify_url": "https://webhook.site/1a2d24e8-1594-4569-bc35-079049e4d805",
  "notify_secret": "Cf9mx4nAvRuy5vwBY2FCtaKr"
}
```

### 401

Not authorized

- `message` (string)

Example:

```json
{
  "message": "some_error_message"
}
```

### 403

No permission to initiate this refund from this payment

- `message` (string)

Example:

```json
{
  "message": "some_error_message"
}
```

### 404

Payment reference to refund from not found

- `message` (string)

Example:

```json
{
  "message": "some_error_message"
}
```

### 409

Refund Processing Error - The refund cannot be processed

- `message` (string)

Example:

```json
{
  "message": "some_error_message"
}
```

### 422

Validation Error - There are 1 or more errors in the request body

- `message` (string)
  Main error message
- `errors` (any[])
  - `message` (string)
    Additional error messages
  - `path` (string)
    JSON object key that has the error

Example:

```json
{
  "message": "validation_error",
  "errors": [
    {
      "message": "invalid",
      "path": "api_id"
    }
  ]
}
```