post https://{providerApiEndpoint}/payments//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"
}