Refund Payment

post https://{providerApiEndpoint}/payments/{paymentId}/refunds

Refunds a payment that was previously settled. You can expect partial refunds.

Request body

Name	Type	Mandatory	Description
`requestId`	string	Yes	Provider's settlement identifier
`settleId`	number	Yes	The authorization identifier for this payment
`paymentId`	string	Yes	VTEX payment ID from this payment
`tid`	string	Yes	Provider's unique identifier for the transaction
`value`	number	Yes	The amount to be settled/captured
`transactionId`	string	Yes	VTEX identifier for this transaction
`recipients`	array		Array containing the information for the recipients of this payment in case the Payment Provider is configured to allow the split of payments
↳`id`	string	Yes	Recipient identifier
↳`name`	string	Yes	Recipient name
↳`documentType`	string	Yes	Recipient document type
↳`document`	string	Yes	Recipient document number
↳`role`	string	Yes	Indicates if the recipient is the seller or the marketplace
↳`chargeProcessingFee`	boolean		Indicates whether or not this recipient is charged for processing fees
↳`chargebackLiable`	boolean		Indicates whether or not this recipient is liable to chargebacks
↳`amount`	number	Yes	Amount due to this recipient
`sandboxMode`	boolean		Indicates whether or not this request is being sent from a sandbox environment

Response body

Name	Type	Mandatory	Description
`paymentId`	string	Yes	The same `paymentId` sent in the request
`refundId`	string		Provider's refund identifier (if the operation has failed you MUST return `null`)
`value`	decimal	Yes	The amount that was refunded (if the operation has failed you MUST return `0`)
`code`	string		Provider's operation/error code to be logged (return `refund-manually` if you do not support this operation, so we can send a notification to the merchant)
`message`	string		Provider's operation/error message to be logged
`requestId`	string	Yes	The same `requestId` sent in the request

Request examples and their responses

curl --location --request POST 'https://{{providerApiEndpoint}}/payments/{{paymentId}}/refunds' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
    "transactionId": "D3AA1FC8372E430E8236649DB5EBD08E",
    "settleId": "Q5C1A4E20D3B4E07B7E871F5B5BC9F91",
    "value": 57.0,
    "requestId": "LA4E20D3B4E07B7E871F5B5BC9F91"
}'

curl --location --request POST 'https://{{providerApiEndpoint}}/payments/{{paymentId}}/refunds' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
    "transactionId": "D3AA1FC8372E430E8236649DB5EBD08E",
    "settleId": "Q5C1A4E20D3B4E07B7E871F5B5BC9F91",
    "value": 57.0,
    "requestId": "LA4E20D3B4E07B7E871F5B5BC9F91"
}'

curl --location --request POST 'https://{{providerApiEndpoint}}/payments/{{paymentId}}/refunds' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
    "transactionId": "D3AA1FC8372E430E8236649DB5EBD08E",
    "settleId": "Q5C1A4E20D3B4E07B7E871F5B5BC9F91",
    "value": 57.0,
    "requestId": "LA4E20D3B4E07B7E871F5B5BC9F91"
}'

{
  "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
  "refundId": "2EA354989E7E4BBC9F9D7B66674C2574"
  "value": 57,
  "code": null,
  "message": "Sucessfully refunded",
  "requestId": "LA4E20D3B4E07B7E871F5B5BC9F91"
}

{
  "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
  "refundId": null,
  "value": 0,
  "code": "ERR123",
  "message": "Refund has failed due to an internal error",
  "requestId": "LA4E20D3B4E07B7E871F5B5BC9F91"
}

{
  "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
  "refundId": null,
  "value": 0,
  "code": "refund-manually",
  "message": "This payment needs to be manually refunded",
  "requestId": "LA4E20D3B4E07B7E871F5B5BC9F91"
}