---
title: "Process a refund of a transaction (Poslink V2)"
method: POST
path: "/poslink/v2/refunds"
tags: ["Refunds"]
---

# Process a refund of a transaction (Poslink V2)

`POST /poslink/v2/refunds`

## Request

- Base URL: `https://api.teya.com`
- URL: `https://api.teya.com/poslink/v2/refunds`
- Auth: OAuth 2
  - Authorization code: `https://id.teya.com/oauth/v2/oauth-authorize`
  - Token URL: `https://id.teya.com/oauth/v2/oauth-token`
- TypeScript: <https://skmtc.dev/teya/apis/poslink-api/docs/poslink/v2/refunds/post.ts> (a function with typed inputs; its response is checked against the schema)

This API call is used to process the refund of a previous transaction using the POSLink V2 endpoint.

## Headers

- `Idempotency-Key` string: A unique key to identify the request. If the request is repeated with the same key, the same response will be returned. If the request is repeated with a different key or without a key, a new refund will be created.

## Request body

- RefundRequest: A request to refund a transaction
  - `transaction_id` string, required: Identifies the original payment to refund. Send the `gateway_payment_id` of the original payment, delivered when that payment completes on its status stream (`GET /poslink/v3/payment-requests/{payment-request-id}`). Do **not** send the deprecated `transaction_id` from the V1 payment request response: despite the matching name it is a different identifier and will be rejected with `404 TRANSACTION_NOT_FOUND`.
  - `terminal_id` string: Optional, and only valid when authenticating with client credentials (M2M) for delegated access. Sending `terminal_id` with a user token is rejected with `403 FORBIDDEN` on every attempt. POSLink refunds are referenced online refunds - the terminal is derived from the original payment - so it can safely be omitted.
  - `merchant_reference` string: An identifier referencing the transaction on the client's side
  - `amount` integer, required: A positive integer representing the total amount to refund in the smallest currency unit (e.g., 100 cents to charge $1). The currency is the same as the original transaction. HUF follows ISO 4217 here, so `250000` means 2500 Ft.
  - `currency` string: The ISO 4217 currency code (e.g., 'EUR', 'USD'). Required for CIBA authentication flow
  - `basket_transaction_id` string, uuid: Unique identifier of basket-data transaction

## Response `201`

Refund processed

- RefundResponseV3: A response to refund a transaction
  - `transaction_id` string, required: Unique identifier of the refund that was just created. This is **not** the identifier of the original payment that was sent in the request.
  - `refund_amount` Amount, required
    - `amount` integer, required: A positive integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1)
    - `currency` string, required: Currency code (e.g. `USD`, `GBP`, `EUR`) following ISO-4217 format.
  - `status` 'SUCCESS' | 'FAILURE' | 'PENDING', required: The status of the transaction
  - `transaction_type` 'REFUND' | 'REVERSAL', required: The type of the transaction: REFUND or REVERSAL
  - `status_reason` 'ACCOUNT_INVALID' | 'CANNOT_VALIDATE_AUTHENTICATION' | 'CARD_COUNT_EXCEEDED' | 'CARD_DECLINED' | 'CARD_EXPIRED' | 'CARD_LIMIT_EXCEEDED' | 'CARD_NOT_ACTIVE' | 'DISABLED_ACCOUNT' | 'DO_NOT_HONOR' | 'ECOM_NEGATIVE_CARD_AUTHENTICATION_VERIFICATION' | 'EXCEEDS_AMOUNT_LIMIT' | 'FORMAT_ERROR' | 'INCORRECT_CARD_AUTHENTICATION' | 'INSUFFICIENT_FUNDS' | 'INVALID_CARD_NUMBER' | 'INVALID_TRANSACTION' | 'ISSUER_DECLINED' | 'LOST_OR_STOLEN' | 'MERCHANT_CONFIGURATION' | 'PIN_LIMIT_EXCEEDED' | 'PROCESSOR_UNAVAILABLE' | 'RESTRICTED_CARD' | 'SCA_PIN_REQUIRED' | 'SCA_REQUIRED' | 'SUSPECTED_FRAUD' | 'TEMPORARY_ISSUE_RETRY' | 'TIMEOUT' | 'TRANSACTION_NOT_ALLOWED' | 'UNABLE_TO_ROUTE_TRANSACTION' | 'UNSUPPORTED_ISSUER' | 'NEGATIVE_BALANCE_LIMIT' | 'OTHER': Reason for `FAILURE` status
  - `card_acceptor_id` string, required: `mid` or `card_acceptor_id` (ISO 8583 field standard). Used to unique identify the merchant in the transaction.
  - `issuer_result` RefundIssuerResult, required
    - `approval_code` string: Identifier of the authorisation returned by the issuer. When the transaction is not authorised, this field is empty
    - `response_code` string: Response code returned by the issuer, indicating the result of the operation
  - `created_at` string, date-time: The date and time the refund was created (in ISO 8601 with time-zone).
  - `dcc` DccResponse
    - `cardholder_amount` Amount, required
      - `amount` integer, required: A positive integer representing the total amount in the smallest currency unit (e.g., 100 cents to charge $1)
      - `currency` string, required: Currency code (e.g. `USD`, `GBP`, `EUR`) following ISO-4217 format.
    - `conversion_rate` string, required: Conversion rate used to calculate the cardholder amount
    - `markup` string, required: Markup of the exchange rate
    - `ecb_markup` string: Markup of the exchange rate over the ECB exchange rate. Only provided when both currencies are EEA currencies.

## Other responses

- `202`: Refund is being processed asynchronously
- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `500`: Internal Server Error
- `503`: Service Unavailable
- `523`: Origin Unavailable

---

[API](https://skmtc.dev/teya/apis/poslink-api.md) - [All operations](https://skmtc.dev/teya/apis/poslink-api/llms.txt) - [OpenAPI document](https://skmtc.dev/teya/apis/poslink-api/revisions/cc7c1bd11e93?raw)