Refund

A refund returns funds to the customer’s payment instrument for a previously completed sale or capture. You can issue a full refund or a partial refund by specifying an amount.

Safe retries for this POST endpoint use the Idempotency-Key header. Reuse the same key only when retrying the exact same request body. See Idempotency.

curl --request POST \
  --url https://api.smartretry.com/v1/payments/refund/ABC123 \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: refund-20260331-001' \
  --data '{
    "transaction_reference_id": "TX8A3F2C",
    "order_reference_id": "OR7B9E1D",
    "merchant_transaction_id": "refund-20260331-001",
    "amount": 25.00
  }'

import requests

response = requests.post(
    "https://api.smartretry.com/v1/payments/refund/ABC123",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "refund-20260331-001"
    },
    json={
        "transaction_reference_id": "TX8A3F2C",
        "order_reference_id": "OR7B9E1D",
        "merchant_transaction_id": "refund-20260331-001",
        "amount": 25.00
    }
)

print(response.json())

const response = await fetch(
  "https://api.smartretry.com/v1/payments/refund/ABC123",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
      "Idempotency-Key": "refund-20260331-001"
    },
    body: JSON.stringify({
      transaction_reference_id: "TX8A3F2C",
      order_reference_id: "OR7B9E1D",
      merchant_transaction_id: "refund-20260331-001",
      amount: 25.00
    })
  }
);

const data = await response.json();
console.log(data);

{
  "transaction_id": "TX2E6G8H",
  "order_id": "OR7B9E1D",
  "merchant_transaction_id": "refund-20260331-001",
  "accepted": true
}

{
  "type": "https://api.smartretry.com/errors/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "transaction_reference_id does not refer to a refundable transaction",
  "reason_code": "INVALID_TRANSACTION_REFERENCE"
}

Path parameters

terminal_friendly_id

string

required

Your terminal identifier. Exactly 6 characters.

Request body

transaction_reference_id

string

required

The transaction_id of the sale or capture you want to refund. Exactly 8 characters.

order_reference_id

string

required

The order_id associated with the transaction you want to refund. Exactly 8 characters.

merchant_transaction_id

string

Your unique identifier for this refund transaction. Must be different from the merchant_transaction_id of the original transaction.

amount

number

Amount to refund in major currency units (e.g., 25.00 for $25.00). If omitted, the full transaction amount is refunded. Partial refunds are supported - you can issue multiple partial refunds as long as the total does not exceed the original transaction amount.

currency

string

Three-letter ISO 4217 currency code. If omitted, the currency of the original transaction is used.

Response

transaction_id

string

required

SmartRetry’s unique identifier for this refund transaction. Exactly 8 characters.

order_id

string

required

The order identifier, matching the order_id from the original transaction.

merchant_transaction_id

string

required

The merchant_transaction_id you provided in the request, echoed back for confirmation.

accepted

boolean

required

true if the refund was accepted for processing. Poll the status endpoint using the returned transaction_id to confirm the refund outcome.

To refund only part of a transaction, provide an amount less than the original transaction total. You can issue multiple partial refunds against the same transaction.

You cannot refund a pre-authorization that has not yet been captured. Use the void endpoint to cancel a pre-authorization before capture.

Capture

Void

curl --request POST \
  --url https://api.smartretry.com/v1/payments/refund/ABC123 \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: refund-20260331-001' \
  --data '{
    "transaction_reference_id": "TX8A3F2C",
    "order_reference_id": "OR7B9E1D",
    "merchant_transaction_id": "refund-20260331-001",
    "amount": 25.00
  }'

import requests

response = requests.post(
    "https://api.smartretry.com/v1/payments/refund/ABC123",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "refund-20260331-001"
    },
    json={
        "transaction_reference_id": "TX8A3F2C",
        "order_reference_id": "OR7B9E1D",
        "merchant_transaction_id": "refund-20260331-001",
        "amount": 25.00
    }
)

print(response.json())

const response = await fetch(
  "https://api.smartretry.com/v1/payments/refund/ABC123",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
      "Idempotency-Key": "refund-20260331-001"
    },
    body: JSON.stringify({
      transaction_reference_id: "TX8A3F2C",
      order_reference_id: "OR7B9E1D",
      merchant_transaction_id: "refund-20260331-001",
      amount: 25.00
    })
  }
);

const data = await response.json();
console.log(data);

{
  "transaction_id": "TX2E6G8H",
  "order_id": "OR7B9E1D",
  "merchant_transaction_id": "refund-20260331-001",
  "accepted": true
}

{
  "type": "https://api.smartretry.com/errors/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "transaction_reference_id does not refer to a refundable transaction",
  "reason_code": "INVALID_TRANSACTION_REFERENCE"
}

Overview

Payments

Recurring

Future Transactions

Path parameters

Request body

Response

​Path parameters

​Request body

​Response

Path parameters

Request body

Response