> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waypay.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Refund

> Create a refund request for a processed transaction

## Overview

This endpoint allows you to initiate a refund for a previously completed transaction. Refunds can be full or partial amounts.

## Path Parameters

<ParamField path="version" type="string" required>
  API version (e.g., "1")
</ParamField>

## Request Body

<ParamField body="trxnRef" type="string" required>
  Transaction reference number to refund
</ParamField>

<ParamField body="amount" type="number">
  Refund amount (minimum 10). If not provided, full transaction amount will be refunded
</ParamField>

<ParamField body="reason" type="string">
  Reason for refund (max 500 characters)
</ParamField>

<ParamField body="signature" type="string" required>
  Request signature for authentication. A 32-character lowercase hexadecimal string generated using MD5 hash.

  <Warning>Never expose your secret key in client-side code or public repositories.</Warning>

  See the [Signature Guide](/signature-guide) for implementation details.
</ParamField>

## Response

<ResponseField name="id" type="uuid">
  Unique refund identifier
</ResponseField>

<ResponseField name="paymentIntentId" type="uuid">
  Associated payment intent ID
</ResponseField>

<ResponseField name="amount" type="number">
  Refund amount
</ResponseField>

<ResponseField name="currency" type="string">
  Currency code
</ResponseField>

<ResponseField name="reason" type="string">
  Refund reason
</ResponseField>

<ResponseField name="status" type="integer">
  Refund status:

  * `0` - Pending
  * `1` - Approved
  * `2` - Processing
  * `3` - Completed
  * `4` - Failed
  * `5` - Cancelled
  * `6` - Rejected
  * `7` - Expired
</ResponseField>

<ResponseField name="isLive" type="boolean">
  Whether this is a live or test refund
</ResponseField>

<ResponseField name="requestedAt" type="datetime">
  When the refund was requested
</ResponseField>

<ResponseField name="approvedAt" type="datetime">
  When the refund was approved
</ResponseField>

<ResponseField name="processedAt" type="datetime">
  When the refund was processed
</ResponseField>

<ResponseField name="attemptCount" type="integer">
  Number of processing attempts
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://gateway.dev.waypay.live/Gateway/v1/Refunds \
    --header 'SWICH-API-Key: pk_test_xxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data '{
      "trxnRef": "TXN20251212123456",
      "amount": 250,
      "reason": "Customer requested refund",
      "signature": "d4e5f6789012345678abcdef1234567"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://gateway.dev.waypay.live/Gateway/v1/Refunds', {
    method: 'POST',
    headers: {
      'SWICH-API-Key': 'pk_test_xxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      trxnRef: 'TXN20251212123456',
      amount: 250,
      reason: 'Customer requested refund',
      signature: 'd4e5f6789012345678abcdef1234567'
    })
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://gateway.dev.waypay.live/Gateway/v1/Refunds',
      headers={
          'SWICH-API-Key': 'pk_test_xxxxxxxx',
          'Content-Type': 'application/json'
      },
      json={
          'trxnRef': 'TXN20251212123456',
          'amount': 250,
          'reason': 'Customer requested refund',
          'signature': 'd4e5f6789012345678abcdef1234567'
      }
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "paymentIntentId": "660e8400-e29b-41d4-a716-446655440001",
    "amount": 250,
    "currency": "PKR",
    "reason": "Customer requested refund",
    "status": 0,
    "isLive": true,
    "requestedAt": "2025-12-12T10:30:00Z",
    "approvedAt": null,
    "processedAt": null,
    "attemptCount": 0
  }
  ```
</ResponseExample>