Create Refund

curl --location 'https://api.sandbox.wepayout.co/v2/payin/payments/payin-refund/63730' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN_HERE' \
--data-raw '{
  "amount": 1000,
  "reason": "Customer requested cancellation",
  "splits": [
    { "wallet_uuid": "WALLET_UUID", "amount": 1000 }
  ]
}'

curl --location 'https://api.sandbox.wepayout.co/v2/payin/payments/payin-refund/63730' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN_HERE' \
--data-raw '{
  "amount": 1000,
  "reason": "Customer requested cancellation",
  "splits": [
    { "wallet_uuid": "WALLET_UUID", "percent": 50 }
  ]
}'

{
  "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"
}

{
  "message": "Insufficient balance"
}

{
  "error": "Unauthorized"
}

{
  "message": "Payin not found"
}

{
  "message": "The given data was invalid.",
  "errors": {
    "amount": [
      "The amount field is required."
    ]
  }
}

{
  "error": "Internal server error"
}

POST

payin

payments

payin-refund

{id}

curl --location 'https://api.sandbox.wepayout.co/v2/payin/payments/payin-refund/63730' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN_HERE' \
--data-raw '{
  "amount": 1000,
  "reason": "Customer requested cancellation",
  "splits": [
    { "wallet_uuid": "WALLET_UUID", "amount": 1000 }
  ]
}'

curl --location 'https://api.sandbox.wepayout.co/v2/payin/payments/payin-refund/63730' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN_HERE' \
--data-raw '{
  "amount": 1000,
  "reason": "Customer requested cancellation",
  "splits": [
    { "wallet_uuid": "WALLET_UUID", "percent": 50 }
  ]
}'

{
  "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"
}

{
  "message": "Insufficient balance"
}

{
  "error": "Unauthorized"
}

{
  "message": "Payin not found"
}

{
  "message": "The given data was invalid.",
  "errors": {
    "amount": [
      "The amount field is required."
    ]
  }
}

{
  "error": "Internal server error"
}

Some important rules

Only charges credited to the wallet can be refunded.
The wallet(s) being debited must have at least the refund amount available. See Which wallet is debited.
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”.

Which wallet is debited

For Pix charges, the wallet debited by the refund is defined by the pix.refund_mode sent when the charge was created (see Create Charge (Pix)):

`refund_mode`	Wallet debited
`FULL_REFUND_MERCHANT` (default)	The wallet of the merchant that created the charge, even if the charge has splits.
`FULL_REFUND_RECIPIENT`	The wallet that received the split. If the charge has more than one wallet in `splits`, the refund is rejected.
`REFUND_BY_SPLIT`	The wallets informed in the `splits` field of this request, which is mandatory in this mode.

Regardless of the refund_mode, a refund request that informs splits debits the wallets listed in it. Use it to debit a split wallet when the charge was created without refund_mode.

The balance of every wallet being debited is checked before the refund is created. If any of them does not cover its part, the request is rejected with HTTP 400 and no refund is created.

Path Parameters

integer

required

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

Request Body

integer

required

The refund amount in the smallest currency unit (e.g., 1000 to refund R$10.00).Example: 1000

string

required

Reason for the refund.Example: "Teste"

string

URL to receive webhook notifications about refund status changes.

array

Wallets to be debited by this refund. Mandatory when the charge was created with refund_mode = REFUND_BY_SPLIT. See Which wallet is debited.The sum of the splits cannot be greater than the refund amount. Any remaining amount is debited from the wallet of the merchant that created the charge.

Show Split Object

string

required

UUID of the wallet to be debited. It must be one of the wallets in the splits of the charge, and cannot be repeated in the list.

integer

Amount to debit from this wallet, in the smallest currency unit (e.g., 1000 for R$10.00). Required if percent is not provided. Cannot be sent together with percent.Min: 1

number

Percentage of the refund amount to debit from this wallet. Required if amount is not provided. Cannot be sent together with amount.Min: 0.01, Max: 100

curl --location 'https://api.sandbox.wepayout.co/v2/payin/payments/payin-refund/63730' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN_HERE' \
--data-raw '{
  "amount": 1000,
  "reason": "Customer requested cancellation",
  "splits": [
    { "wallet_uuid": "WALLET_UUID", "amount": 1000 }
  ]
}'

curl --location 'https://api.sandbox.wepayout.co/v2/payin/payments/payin-refund/63730' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN_HERE' \
--data-raw '{
  "amount": 1000,
  "reason": "Customer requested cancellation",
  "splits": [
    { "wallet_uuid": "WALLET_UUID", "percent": 50 }
  ]
}'

In the By percent example, R$5.00 (50% of the refund) is debited from the split wallet and the remaining R$5.00 from the merchant wallet.

Response

integer

Refund ID.

integer

The ID of the payin (cash-in) being refunded.

integer

Current status ID of the refund.Status codes:

2: Requested
4: Paid (refund completed)
5: Error

object

User who created the refund.

Show User

integer

User ID.

string

User name.

integer

Client ID.

integer

Refund amount.

array

History of status changes.

Show Status History Item

integer

Status history ID.

integer

Status ID.

string

Status name.

integer

Notification flag.

string

When this status was set.

string

End-to-end ID (for Pix transactions). Can be null.

string

Reason for the refund.

string

Error code from wallet (if any). Can be null.

string

URL for webhook notifications. Can be null.

string

Refund created date.

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"
}

{
  "message": "Insufficient balance"
}

{
  "error": "Unauthorized"
}

{
  "message": "Payin not found"
}

{
  "message": "The given data was invalid.",
  "errors": {
    "amount": [
      "The amount field is required."
    ]
  }
}

{
  "error": "Internal server error"
}

HTTP	Message	When
`400`	`Insufficient balance`	A wallet being debited does not have the refund amount (or its part of it) available.
`400`	`Refund of sub-wallet or sub merchante discounted charges, not possible for charges with more than one sub-wallet or sub merchant.`	The charge uses `FULL_REFUND_RECIPIENT` and has more than one wallet in `splits`.
`400`	`This charge cannot be reversed`	The charge uses `REFUND_BY_SPLIT` and the request has no `splits`.
`422`	`One or more recipients does not belongs to the Payin charge`	A `splits[].wallet_uuid` is not one of the wallets in the `splits` of the charge.
`422`	`The sum of the splits amount cannot be greater than the refund amount`	The sum of `splits` is greater than the refund `amount`.

Important Information About the Webhook metadata

Refund Status

Status	Description	Status ID
Requested	The refund has been requested.	2
Paid	The refund has been successfully paid.	4
Error	An 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) ✗

Account

Banks

Payin

Payout

KYC

Markup

Some important rules

Sandbox Testing

Which wallet is debited

Path Parameters

Request Body

Response

Important Information About the Webhook metadata

Refund Status

Webhook Payload Examples:

Refund Status Flow

​Some important rules

​Sandbox Testing

​Which wallet is debited

​Path Parameters

​Request Body

​Response

​Errors related to the debited wallet

​Important Information About the Webhook metadata

​Refund Status

​Webhook Payload Examples:

​Refund Status Flow

Some important rules

Sandbox Testing

Which wallet is debited

Path Parameters

Request Body

Response

Errors related to the debited wallet

Important Information About the Webhook metadata

Refund Status

Webhook Payload Examples:

Refund Status Flow