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

# Create a Refund — POST /v1/refunds

> Issue a full or partial refund against a captured payment. Accepts transactionId, amount, currency, and optional reason. Returns the refund record.

Use this endpoint to issue a full or partial refund against a previously captured payment. Refunds are processed through the same upstream provider that handled the original transaction, so processing times and availability depend on that provider. For partial refunds, pass an amount less than the original payment; for a full refund, pass the original payment amount exactly.

<Note>
  Use the `Idempotency-Key` header on every refund request. If a request fails or times out, retrying with the same key guarantees you will not issue a duplicate refund.
</Note>

## Headers

<ParamField header="X-API-Key" type="string" required>
  Your secret API key. Keep this value server-side and never expose it in client code.
</ParamField>

<ParamField header="Idempotency-Key" type="string" required>
  A unique string you generate per refund attempt. Reuse the same key to safely retry a failed request without creating a duplicate refund.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Body

<ParamField body="transactionId" type="string" required>
  UUID of the original captured payment you want to refund.
</ParamField>

<ParamField body="amount" type="string" required>
  Refund amount as a decimal string (for example, `"10.00"`). Must not exceed the original payment amount. To issue a full refund, pass the exact original payment amount.
</ParamField>

<ParamField body="currency" type="string" required>
  Three-letter ISO 4217 currency code. Must match the currency of the original payment. The value is automatically uppercased before processing.
</ParamField>

<ParamField body="reason" type="string">
  Human-readable reason for the refund. Maximum 500 characters. Stored on the refund record and forwarded to the upstream provider where supported.
</ParamField>

## Response

<ResponseField name="data" type="object">
  <Expandable title="data properties">
    <ResponseField name="id" type="string">
      Accelebit-generated UUID for this refund record.
    </ResponseField>

    <ResponseField name="transactionId" type="string">
      UUID of the original payment that was refunded.
    </ResponseField>

    <ResponseField name="amount" type="string">
      Refund amount as a decimal string, exactly as submitted.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Three-letter ISO 4217 currency code.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the refund. The initial value is `"created"`. Status transitions are delivered via webhook as the upstream provider processes the refund.
    </ResponseField>

    <ResponseField name="reason" type="string">
      The reason string provided in the request, if any.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp indicating when the refund record was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.gateway.accelebit.com/v1/refunds \
    -H "Content-Type: application/json" \
    -H "X-API-Key: smtgw_sk_test_your_secret_key" \
    -H "Idempotency-Key: refund_abc123" \
    -d '{
      "transactionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "amount": "55.00",
      "currency": "EUR",
      "reason": "Customer requested refund"
    }'
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.gateway.accelebit.com/v1/refunds', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.ACCELEBIT_SECRET_KEY!,
      'Idempotency-Key': `refund_${crypto.randomUUID()}`,
    },
    body: JSON.stringify({
      transactionId: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
      amount: '55.00',
      currency: 'EUR',
      reason: 'Customer requested refund',
    }),
  });

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

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

  response = requests.post(
      'https://api.gateway.accelebit.com/v1/refunds',
      headers={
          'Content-Type': 'application/json',
          'X-API-Key': ACCELEBIT_SECRET_KEY,
          'Idempotency-Key': f'refund_{uuid.uuid4()}',
      },
      json={
          'transactionId': 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
          'amount': '55.00',
          'currency': 'EUR',
          'reason': 'Customer requested refund',
      },
  )

  result = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 201 - Refund Created theme={null}
  {
    "data": {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "transactionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "amount": "55.00",
      "currency": "EUR",
      "status": "created",
      "reason": "Customer requested refund",
      "createdAt": "2026-04-09T14:00:00.000Z"
    }
  }
  ```

  ```json 404 - Transaction Not Found theme={null}
  {
    "data": null,
    "error": {
      "status": 404,
      "name": "NOT_FOUND",
      "message": "Transaction f47ac10b-58cc-4372-a567-0e02b2c3d479 not found"
    }
  }
  ```

  ```json 400 - Validation Error theme={null}
  {
    "data": null,
    "error": {
      "status": 400,
      "name": "INVALID_REQUEST",
      "message": "Amount must be a decimal string like \"10.00\""
    }
  }
  ```
</ResponseExample>