---
title: "Process a refund"
method: POST
path: "/transaction/{apiKey}/refund"
tags: ["transaction"]
---

# Process a refund

`POST /transaction/{apiKey}/refund`

## Request

- Base URL: `https://gateway.tillpayments.com/api/v3`
- URL: `https://gateway.tillpayments.com/api/v3/transaction/{apiKey}/refund`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/tillpayments/apis/till-payments-gateway/docs/transaction/:apiKey/refund/post.ts> (a function with typed inputs; its response is checked against the schema)

## Path parameters

- `apiKey` string, required

## Request body

- Refund
  - `merchantTransactionId` string, required
  - `additionalId1` string
  - `additionalId2` string
  - `referenceSchemeLifecycleIdentifier` string
  - `extraData` ExtraData
  - `pspPassthroughData` PspPassthroughData
  - `merchantMetaData` string
  - `referenceUuid` string, required
  - `amount` string, required
  - `currency` string, required
  - `callbackUrl` string
  - `transactionToken` string
  - `description` string
  - `items` object[]
    - `identification` string
    - `name` string
    - `description` string
    - `quantity` union
      - integer
      - string
    - `price` union
      - number
      - string
    - `currency` string
    - `l2l3Data` object
      - `type` string
      - `unit` string
      - `unitPrice` string
      - `discount` string
      - `discountRate` string
      - `shippingAmount` string
      - `taxAmount` string
      - `taxRate` string
      - `commodityCode` string
      - `taxDetails` object[]
        - `type` string
        - `amount` string
        - `rate` string
        - `code` string
        - `taxId` string
        - `applied` string
        - `exemptionCode` string
    - `extraData` ExtraData
  - `splits` object[]
    - `identification` string
    - `amount` string
    - `currency` string
    - `sellerMerchantGuid` string
    - `sellerMerchantExternalId` string
    - `commissionFee` object
      - `amount` string
      - `currency` string
  - `l2l3Data` L2L3Data
    - `taxAmount` string
    - `vatRegistrationNumber` string
    - `nationalTaxIncluded` string
    - `discountAmount` string
    - `commodityCode` string
    - `freightAmount` string
    - `freightTaxAmount` string
    - `dutyAmount` string
    - `taxDetails` object[]
      - `type` string
      - `amount` string
      - `rate` string
      - `code` string
      - `taxId` string
      - `applied` string
      - `exemptionCode` string

## Response `200`

Transaction response

- TransactionResponse
  - `success` boolean
  - `uuid` string
  - `purchaseId` string
  - `returnType` 'FINISHED' | 'REDIRECT' | 'HTML' | 'PENDING' | 'ERROR' | 'PENDING_DCC'
  - `redirectType` 'iframe' | 'fullpage' | '3ds'
  - `redirectUrl` string
  - `redirectQRCode` string: DataUrl
  - `htmlContent` string
  - `paymentDescriptor` string
  - `paymentMethod` string
  - `adapterMerchantTransactionId` string: Adapter/PSP-side merchant transaction identifier recorded for transaction matching and reconciliation. Omitted when unavailable.
  - `amount` string
  - `surchargeAmount` string
  - `gstAmount` string
  - `totalAmount` string
  - `returnData` union
    - ReturnCardData
      - `_TYPE` 'cardData'
      - `type` string
      - `firstName` string
      - `lastName` string
      - `country` string
      - `cardHolder` string
      - `expiryMonth` string
      - `expiryYear` string
      - `binDigits` string
      - `firstSixDigits` string
      - `lastFourDigits` string
      - `fingerprint` string
      - `binBrand` string
      - `binBank` string
      - `binType` string
      - `binLevel` string
      - `binCountry` string
      - `binSegment` 'Consumer' | 'Business' | 'Commercial' | 'Government' | 'Unknown'
      - `binRawData` object
        - `type` string
        - `data` object
      - `threeDSecure` string
      - `eci` string
      - `merchantAdviceCode` string
      - `parsedMerchantAdviceCode` string
      - `schemeTransactionIdentifier` string
      - `schemeLifecycleIdentifier` string
      - `referenceSchemeLifecycleIdentifier` string
      - `cardUpdateStatus` 'updated' | 'contact' | 'new-expiry' | 'closed': Account updater transaction status
      - `cardUpdatedAt` string, date: Last run of the batch
      - `cardUpdatePausedUntil` string, date: Updates paused until this date
    - ReturnPhoneData
      - `_TYPE` 'phoneData'
      - `phoneNumber` string
      - `country` string
      - `operator` string
    - ReturnIbanData
      - `_TYPE` 'ibanData'
      - `accountOwner` string
      - `iban` string
      - `bic` string
      - `mandateId` string
      - `mandateDate` string
      - `bankName` string
      - `bankBranchName` string
      - `country` string
    - ReturnWalletData
      - `_TYPE` 'walletData'
      - `walletReferenceId` string
      - `walletOwner` string
      - `walletType` string
  - `scheduleData` ScheduleData
    - `scheduleId` string
    - `scheduleStatus` 'ACTIVE' | 'PAUSED' | 'CANCELLED' | 'ERROR' | 'CREATE-PENDING'
    - `scheduledAt` string
    - `merchantMetaData` string
  - `customerProfileData` CustomerProfileData
    - `profileGuid` string
    - `customerIdentification` string
    - `paymentToken` string
    - `markAsPreferred` boolean
  - `riskCheckData` object
    - `riskCheckResult` 'APPROVED' | 'DECLINED' | 'REVIEW'
    - `riskScore` number
    - `threeDSecureRequired` boolean
  - `errors` object[]
    - `errorMessage` string
    - `errorCode` integer
    - `adapterMessage` string
    - `adapterCode` string
  - `adapterMessage` string
  - `adapterCode` string
  - `extraData` ExtraData
  - `dccData` object
    - `uuid` string
    - `originalAmount` string
    - `originalCurrency` string
    - `convertedAmount` string
    - `convertedCurrency` string
    - `conversionRate` number
    - `disclaimer` string

## Changes

- **2026-11-07** `42c40d316a83`: 9 info
  - added the new optional request property `referenceSchemeLifecycleIdentifier`
  - added the optional property `adapterMerchantTransactionId` to the response with the `200` status
  - added the optional property `amount` to the response with the `200` status
  - added the optional property `customerProfileData/paymentToken` to the response with the `200` status
  - …5 more
- **2025-04-27** `5d765c6bfe90`: 4 info
  - the `callbackUrl` request property's maxLength was increased from `255` to `4096`
  - added the optional property `returnData/oneOf[#/components/schemas/ReturnCardData]/binRawData` to the response with the `200` status
  - added the optional property `returnData/oneOf[#/components/schemas/ReturnCardData]/binSegment` to the response with the `200` status
  - added the optional property `returnData/oneOf[#/components/schemas/ReturnCardData]/cardUpdatePausedUntil` to the response with the `200` status
- **2024-07-22** `65196339abf0`: 4 breaking, 6 info
  - added the pattern `^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$` to the request property `splits/items/amount`
  - added the pattern `^(([0-9]{1,10})|([0-9]{1,10}\.[0-9]{1,3}))$` to the request property `splits/items/commissionFee/amount`
  - the `splits/items/amount` request property type changed from `number` to `string`
  - the `splits/items/commissionFee/amount` request property type changed from `number` to `string`
  - …6 more

[Operation history](https://skmtc.dev/tillpayments/apis/till-payments-gateway/changes/transaction/:apiKey/refund/post.md)

---

[API](https://skmtc.dev/tillpayments/apis/till-payments-gateway.md) - [All operations](https://skmtc.dev/tillpayments/apis/till-payments-gateway/llms.txt) - [OpenAPI document](https://skmtc.dev/tillpayments/apis/till-payments-gateway/revisions/42c40d316a83?raw)