Creating a Payment Reversal or Refund

Creates a reversal or refund for a payment. Merchant may send this request once or several times to make partial refunds.

For additional information, please see “Payment Reversal and Refund“

Request

PUT /payin/v1/sites/{siteId}/payments/{paymentId}/refunds/{refundId}

Path Parameters

Parameter	Required	Type	Description
siteId	Yes	string	Merchant site identifier
paymentId	Yes	string	Payment identifier. The merchant receives this identifier in the payment notification
refundId	Yes	string	Unique refund identifier in the merchant’s system

Headers

Header	Required	Type	Description
Authorization	Yes	string	API access key. Bearer [access-token]
Content-type	Yes	string	Request content. application/json
Accept	No	string	Response content. application/json

Body Parameters

Parameter	Required	Type	Description
amount	Yes	object	Operation amount
callbackUrl	No	string(256)	Notification URL
comment	No	string(255)	Additional description for the refund
settlementAmount	No	object	Merchant’s settlement amount (when settlement currency differs from the currency of the payment authorization)

Request Example

Payment refund

PUT /partner/payin/v1/sites/test-01/payments/1811/refunds/tcwv3132 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: b2b-api.qiwi.com

{
  "amount": {
    "value": 2.34,
    "currency": "RUB"
  }
}

Response

See also HTTP error codes

Successful Response Parameters

Parameter	Required	Type	Description
refundId	Yes	string	Unique refund identifier in the merchant’s system. Same as in the request
createdDateTime	Yes	string	Operation date and time
amount	Yes	object	Operation amount
status	Yes	object	Operation status
flags	No	string(256)	Additional API commands. REVERSAL — card reversal operation was used for bank card operation

Error Parameters

Parameter	Required	Type	Description
serviceName	Yes	string	Name of the service that produced the error
errorCode	Yes	string	Error code
description	Yes	string	Error description for the merchant
userMessage	Yes	string	Error description for the customer
dateTime	Yes	string	Error date and time
traceId	Yes	string	Error Log unique ID
cause	No	object	Description for the field validation error

Response Examples

Successful responseResponse with error 4xxResponse with error 5xx

{
  "refundId": "tcwv3132",
  "createdDateTime": "2024-03-20T16:32:55.547+03:00",
  "amount": {
    "currency": "RUB",
    "value": "2.34"
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2024-03-20T16:32:55.55+03:00"
  },
  "flags": [
    "REVERSAL"
  ]
}

{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2022-03-05T11:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
}