Skip to main content
POST
/
v2
/
payin
/
payments
/
payin-refund
/
{id}
Create Refund
curl --request POST \
  --url https://api.sandbox.wepayout.com.br/v2/payin/payments/payin-refund/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 123,
  "reason": "<string>",
  "notification_url": "<string>"
}
'
{
  "id": 123,
  "payin_id": 456,
  "status_id": 2,
  "user": {
    "id": 789,
    "name": "João Silva"
  },
  "client_id": 10,
  "refund_amount": 10000,
  "status_history": [
    {
      "id": 1,
      "payin_refund_id": 123,
      "statusId": 1,
      "status_id": 1,
      "name": "Check",
      "notification": 1,
      "created_at": "2026-02-19T12:34:56.000000Z"
    }
  ],
  "end_to_end_id": "E12345678202602191234567890AB",
  "reason": "Customer requested cancellation",
  "wallet_error_code": null,
  "notification_url": "https://example.com/webhook",
  "created_at": "2026-02-19T12:34:56.000000Z",
  "updated_at": "2026-02-19T12:34:56.000000Z"
}

​
Some important rules

  • Only charges credited to the wallet can be refunded.
  • The customer must have at least the refund amount available in the wallet.
  • Pix: can only be returned with 90 days or less.
  • Credit card: 180 days or less.

​
Sandbox Testing

To test refund scenarios in the sandbox environment, the field amount must be one of the following values: 100, 1000, or 10000.Additionally, you must include the field reason with the value “APRO”.

​
Path Parameters

​
id
integer
required
The cash-in ID (payin ID) for which the refund will be created.Example: 63730

​
Request Body

​
amount
integer
required
The refund amount.Example: 10
​
reason
string
required
Reason for the refund.Example: "Teste"
​
notification_url
string
URL to receive webhook notifications about refund status changes.

​
Response

​
id
integer
Refund ID.
​
payin_id
integer
The ID of the payin (cash-in) being refunded.
​
status_id
integer
Current status ID of the refund.Status codes:
  • 2: Requested
  • 4: Paid (refund completed)
  • 5: Error
​
user
object
User who created the refund.
​
client_id
integer
Client ID.
​
refund_amount
integer
Refund amount.
​
status_history
array
History of status changes.
​
end_to_end_id
string
End-to-end ID (for Pix transactions). Can be null.
​
reason
string
Reason for the refund.
​
wallet_error_code
string
Error code from wallet (if any). Can be null.
​
notification_url
string
URL for webhook notifications. Can be null.
​
created_at
string
Refund created date.
​
updated_at
string
Refund update date.
{
  "id": 123,
  "payin_id": 456,
  "status_id": 2,
  "user": {
    "id": 789,
    "name": "João Silva"
  },
  "client_id": 10,
  "refund_amount": 10000,
  "status_history": [
    {
      "id": 1,
      "payin_refund_id": 123,
      "statusId": 1,
      "status_id": 1,
      "name": "Check",
      "notification": 1,
      "created_at": "2026-02-19T12:34:56.000000Z"
    }
  ],
  "end_to_end_id": "E12345678202602191234567890AB",
  "reason": "Customer requested cancellation",
  "wallet_error_code": null,
  "notification_url": "https://example.com/webhook",
  "created_at": "2026-02-19T12:34:56.000000Z",
  "updated_at": "2026-02-19T12:34:56.000000Z"
}

​
Important Information About the Webhook metadata

​
Refund Status

StatusDescriptionStatus ID
RequestedThe refund has been requested.2
PaidThe refund has been successfully paid.4
ErrorAn error occurred during the refund process.5
If an error occurs during the refund process (status 5), the field total_refund_amount will be decremented by the requested amount. When the refund is successfully paid, the amount will be incremented again.

​
Webhook Payload Examples:

Requested: 
{
  "id": 123,
  "payin_id": 456,
  "status": {
    "id": 2,
    "name": "Requested"
  },
  "metadata": {
    "refund_amount": 100.50,
    "total_refund_amount": 250.75
  },
  "reason": "Customer requested cancellation",
  "updated_at": "2026-02-19T12:34:56.000000Z"
}
Error: 
{
  "id": 123,
  "payin_id": 456,
  "status": {
    "id": 5,
    "name": "Error"
  },
  "metadata": {
    "refund_amount": 100.50,
    "total_refund_amount": 150.25
  },
  "reason": "Customer requested cancellation",
  "updated_at": "2026-02-19T12:35:10.000000Z"
}
Paid: 
{
  "id": 123,
  "payin_id": 456,
  "status": {
    "id": 4,
    "name": "Paid"
  },
  "metadata": {
    "refund_amount": 100.50,
    "total_refund_amount": 250.75
  },
  "reason": "Customer requested cancellation",
  "updated_at": "2026-02-19T12:36:22.000000Z"
}

​
Refund Status Flow

Success scenario: 
REQUESTED (2) → PAID (4) ✓
Error scenario: 
REQUESTED (2) → ERROR (5) ✗