Refund Payment

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"
}
Language
Authentication
URL
Click Try It! to start a request and see the response here!