Skip to content

Payment Refund

Payment refund method. Supports both a full refund refunded and a partial refund part_refunded with a specified amount.

URL

Method: POST

  • Production: https://api.pay.kvell.group/v1/orders/{transaction}/refund
  • Stage: https://api.pay.stage.kvell.group/v1/orders/{transaction}/refund

Request parameters

Name Data type Required Description
transaction string Yes Unique transaction number on the merchant's side

Request body parameters

Name Data type Required Description
amount integer No Refund amount in kopecks. If not specified, the full transaction amount is refunded.

Request example

{
  "amount": 1000
}

Request headers

Name Data type Required Description
X-Api-Key string Yes Unique shop identifier
X-Signature string Yes Signature

Generating the signature

The X-Signature signature is generated by concatenating X-Api-Key, transaction, and secret_key. A sha256 hash is generated from the resulting string:

sha256({x-api-key}{transaction}{secret_key})

where secret_key is the secret key found in the merchant's shop settings.

Response

Response example

{
  "id": "b13e1610-f26a-4c49-84e8-0edf1650a026",
  "status": "refunded", // "part_refunded"
  "transaction": "436b4ed3-fc6d-431e-963e-a958a730119c",
  "amount": 100,
  "commission": 1000,
  "inner_commission": 500,
  "description": "TEST Invoice",
  "success_url": "https://success.url",
  "fail_url": "https://fail.url",
  "redirect_url": "https://redirect.url",
  "extra_data": {},
  "fiscal_data": {},
  "split_data": [],
  "additional_data": {},
  "error_code": null,
  "error_message": null,
  "created_at": "2024-05-20T12:55:00.951753+00:00",
  "instrument": "card",
  "ecommerce_type": "payment",
  "operation": {
    "id": "14153172",
    "type": "refund",
    "status": "success",
    "amount": 100,
    "error_code": null,
    "error_message": null,
    "rrn": "612006383862",
    "created_at": "2024-05-20T13:02:41.120000Z"
  }
}

{
  "errors": [
    {
      "message": "string",
      "code": 0
    }
  ]
}

Response parameters

Name Data type Description
id string Transaction ID in the system
status string Transaction status
transaction string Unique transaction number on the merchant's side
amount integer Amount in kopecks
description string Transaction description
created_at string Transaction creation date (UTC)
error_code string Error code
error_message string Error message
commission integer External commission in kopecks
inner_commission integer Internal commission in kopecks
success_url string URL for successful status
fail_url string URL for unsuccessful status
redirect_url string Redirect URL, used if success_url and fail_url are not specified
extra_data json Additional information
fiscal_data json Receipt fiscalization data
split_data array Transaction split data
additional_data json Additional transaction information
operation object The refund operation created by this request: id, type, status, amount, error_code, error_message, rrn, created_at. Fields and statuses are described in «Order operations»

List of statuses

Name Description
new New transaction
processing Transaction is being processed
canceled Transaction rejected
completed Transaction completed
refunded Transaction refunded
part_refunded Transaction partially refunded

Delayed refund

If the bank does not confirm the refund immediately, the method returns 200 with the previous transaction status (for example, completed) and the previous refund_amount, and operation.status is new. This is not a decline: the refund has been sent to the bank and is still being processed.

  1. Save operation.id.
  2. Request the transaction status with with_operations=true and find the operation by id in the operations array.
  3. success — the refund is complete; the transaction status is now refunded or part_refunded.
  4. declined — the bank declined the refund; the transaction status and refund_amount are unchanged; the reason is in error_message.

Do not repeat the refund while the operation is new

A repeated request creates one more refund operation. Wait for success or declined on the existing one.