Creation of a refund | imoje API eng documentation

Creation of a refund Run in API Explorer

POST /{merchantId}/transaction/{transactionId}/refund

This request allows you to make a refund for a paid transaction.

When making multiple refund transactions simultaneously, please allow at least a 5-second delay between each transaction.

For security reasons, refunds can be made:

for BLIK, up to a maximum of 12 months

for imoje pay later, up to a maximum of 12 months

for payment cards, up to 3 years

Path parameters

merchantId string Required

Merchant identifier
transactionId string(uuid) Required

Transaction identifier as UUID v4

Maximum length is 36. Format should match the following pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$.

application/json

Body Required

type string Required

Transaction type

Value is refund.
serviceId string(uuid) Required

Shop identifier as UUID v4

Maximum length is 36. Format should match the following pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$.
amount integer Required

The transaction amount in the smallest currency unit, e.g. pennies.
title string

Transaction title

Maximum length is 255. Format should match the following pattern: ^[A-Za-z0-9#&_\-\,\.\\\\/ \u00C0-\u02C0"']+$.
sendRefundConfirmationEmail boolean

Send an e-mail confirming the refund to the payer. The e-mail is sent after the refund has been successfully processed (status settled) to the e-mail address provided when placing the order.

Responses

200 application/json

Request executed correctly
Hide response attribute Show response attribute object
- transaction object
  
  Hide transaction attributes Show transaction attributes object
  
  id string(uuid)
  
  Transaction identifier as UUID v4
  
  Maximum length is 36. Format should match the following pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$.
  
  type string
  
  Typ transakcji
  
  Value is refund.
  
  status string
  
  Status
  
  Values are new, pending, settled, authorized, rejected, cancelled, or error.
  
  source string
  
  Transaction source
  
  Values are web or api.
  
  created integer | null
  
  Creation date as timestamp
  
  modified integer | null
  
  Modification date as timestamp
  
  serviceId string(uuid)
  
  Shop identifier as UUID v4
  
  Maximum length is 36. Format should match the following pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$.
  
  amount integer
  
  The transaction amount in the smallest currency unit, e.g. pennies.
  
  currency string
  
  Transaction currency in the ISO 4217 standard
  
  Maximum length is 3. Values are PLN, EUR, USD, GBP, CHF, SEK, HUF, CZK, BGN, or RON.
  
  orderId string
  
  Order ID
  
  Maximum length is 100. Format should match the following pattern: ^[A-Za-z0-9#_\-\.\\\\/ \u00C0-\u02C0]+$.
  
  paymentMethod string
  
  Payment method description
  
  Values are blik, pbl, ing, card, wallet, imoje_paylater, wt, or imoje_installments.
  
  paymentMethodCode string
  
  Payment method code
  
  Values are blik, imoje_twisto, paypo, blik_paylater, pragma_go, gpay, applepay, visa_mobile, paypal, ecom3ds, oneclick, recurring, ing, mtransfer, bzwbk, pekao24, inteligo, ipko, getin, noble, creditagricole, alior, millennium, citi, bos, bnpparibas, pocztowy, plusbank, bs, bspb, nest, pbs, cs, mp, kb, rf, pg, pf, cb, uc, posta, sporo, tatra, viamo, vub, wt, wt_split, inbank, or inbank_0.
422 application/json

The payload does not contain the required parameters, contains unacceptable parameters, or the values sent in them do not meet the requirements.
Hide response attribute Show response attribute object
- apiErrorResponse object
  
  Error details
  
  Hide apiErrorResponse attributes Show apiErrorResponse attributes object
  
  code string
  
  Error code
  
  message string
  
  Error message
  
  instance object
  
  Body of the HTTP request sent to imoje.
  
  errors array[object]
  
  List of errors
  
  Hide errors attributes Show errors attributes object
  
  property string
  
  Location of the error
  
  message string
  
  Cause of error

POST /{merchantId}/transaction/{transactionId}/refund

curl \
 --request POST 'https://api.imoje.pl/v1/merchant/{merchantId}/transaction/{transactionId}/refund' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"type":"refund","title":"yourRefundTitle","amount":100,"serviceId":"24737aab-a507-4feb-8248-3f42bfdbb006","sendRefundConfirmationEmail":true}'

Request example

{
  "type": "refund",
  "title": "yourRefundTitle",
  "amount": 100,
  "serviceId": "24737aab-a507-4feb-8248-3f42bfdbb006",
  "sendRefundConfirmationEmail": true
}

Response examples (200)

{
  "transaction": {
    "id": "2eea6c95-51fc-446a-bedc-03e4b197ffd0",
    "type": "refund",
    "amount": 1000,
    "source": "api",
    "status": "settled",
    "created": 1735686000,
    "orderId": "yourOrderId",
    "currency": "PLN",
    "modified": 1735686000,
    "serviceId": "51cd18a7-68dc-49a7-bb23-3854bbc34627",
    "paymentMethod": "blik",
    "paymentMethodCode": "blik"
  }
}

Response examples (422)

{
  "apiErrorResponse": {
    "code": "TRX-ERROR-120100",
    "errors": [],
    "message": "Refund amount too large.",
    "instance": {
      "type": "refund",
      "amount": 2000,
      "serviceId": "51cd18a7-68dc-49a7-bb23-3854bbc34627"
    }
  }
}