Skip to main content
Refund webhooks allow you to receive automatic notifications whenever the status of a credit card refund changes. When you create a refund for a credit card charge, WEpayments processes it asynchronously through the card processor and sends a POST request to your notification URL each time the refund reaches a new status.
This webhook is specific to refunds and is separate from the Credit Card Webhook, which notifies you about the charge (payin) status. A refund generates its own independent notifications.
The payload format described on this page applies to credit card refunds. Refunds for other payment methods (such as Pix) may use a different payload structure — see Create Refund.

​
How It Works

  1. Create a refund for a credited credit card charge and provide a notification_url
  2. Receive notifications automatically each time the refund status changes
  3. Process the payload containing the refund details and amounts
  4. Return a 200 OK response to acknowledge receipt
A credit card charge can only be refunded if it is credited to the wallet and the refund is requested within 180 days of the original payment. See Create Refund for all refund rules.

​
Setting Up the Refund Webhook

To receive notifications, include the notification_url parameter when creating the refund: 
{
  "amount": 10000,
  "reason": "Customer requested cancellation",
  "notification_url": "https://your-domain.com/webhooks/credit-card-refund"
}
Each refund can have its own notification URL, allowing you to route refund notifications to a dedicated endpoint.

​
Refund Statuses

You will receive a webhook for each of the following refund statuses:
Status IDStatus NameDescription
2RequestedThe refund has been requested and is being processed by the card processor.
4PaidThe refund has been successfully completed.
5ErrorAn error occurred while processing the refund.

​
Refund Status Flow

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

​
Webhook Payload

When a credit card refund status changes, you’ll receive a POST request with the following data:
​
id
integer
Unique identifier of the refund.Example: 123
​
payinId
integer
ID of the credit card charge (payin) being refunded.Example: 456
​
statusId
integer
Current refund status ID (2, 4, or 5).
​
user
object
User who created the refund.
​
clientId
integer
Your client ID in the WEpayments system.
​
amountCents
integer
Amount of this refund, in cents.Example: 10000
​
statuses
array
History of all status changes for this refund.
​
endToEndId
string
End-to-end identifier. Used for Pix refunds; typically null for credit card refunds.
​
reason
string
Reason provided when the refund was created.
​
walletErrorCode
string
Error code returned by the processor when the refund fails (status 5). null otherwise.
​
callbackUrl
string
The notification URL configured for this refund.
​
createdAt
string
Refund creation timestamp (ISO 8601 format).
​
updatedAt
string
Timestamp of the last update (ISO 8601 format).

​
Example Payloads

{
  "id": 123,
  "payinId": 456,
  "statusId": 2,
  "user": {
    "id": 789,
    "name": "João Silva"
  },
  "clientId": 10,
  "amountCents": 10000,
  "statuses": [
    {
      "id": 1,
      "statusId": 2,
      "status_id": 2,
      "name": "Requested",
      "notification": 1,
      "createdAt": "2026-02-19T12:34:56.000000Z",
      "created_at": "2026-02-19T12:34:56.000000Z"
    }
  ],
  "endToEndId": null,
  "reason": "Customer requested cancellation",
  "walletErrorCode": null,
  "callbackUrl": "https://your-domain.com/webhooks/credit-card-refund",
  "createdAt": "2026-02-19T12:34:56.000000Z",
  "updatedAt": "2026-02-19T12:34:56.000000Z"
}

{
  "id": 123,
  "payinId": 456,
  "statusId": 4,
  "user": {
    "id": 789,
    "name": "João Silva"
  },
  "clientId": 10,
  "amountCents": 10000,
  "statuses": [
    {
      "id": 1,
      "statusId": 2,
      "status_id": 2,
      "name": "Requested",
      "notification": 1,
      "createdAt": "2026-02-19T12:34:56.000000Z",
      "created_at": "2026-02-19T12:34:56.000000Z"
    },
    {
      "id": 2,
      "statusId": 4,
      "status_id": 4,
      "name": "Paid",
      "notification": 1,
      "createdAt": "2026-02-19T12:36:22.000000Z",
      "created_at": "2026-02-19T12:36:22.000000Z"
    }
  ],
  "endToEndId": null,
  "reason": "Customer requested cancellation",
  "walletErrorCode": null,
  "callbackUrl": "https://your-domain.com/webhooks/credit-card-refund",
  "createdAt": "2026-02-19T12:34:56.000000Z",
  "updatedAt": "2026-02-19T12:36:22.000000Z"
}

{
  "id": 123,
  "payinId": 456,
  "statusId": 5,
  "user": {
    "id": 789,
    "name": "João Silva"
  },
  "clientId": 10,
  "amountCents": 10000,
  "statuses": [
    {
      "id": 1,
      "statusId": 2,
      "status_id": 2,
      "name": "Requested",
      "notification": 1,
      "createdAt": "2026-02-19T12:34:56.000000Z",
      "created_at": "2026-02-19T12:34:56.000000Z"
    },
    {
      "id": 2,
      "statusId": 5,
      "status_id": 5,
      "name": "Error",
      "notification": 1,
      "createdAt": "2026-02-19T12:35:10.000000Z",
      "created_at": "2026-02-19T12:35:10.000000Z"
    }
  ],
  "endToEndId": null,
  "reason": "Customer requested cancellation",
  "walletErrorCode": "PROCESSOR_ERROR",
  "callbackUrl": "https://your-domain.com/webhooks/credit-card-refund",
  "createdAt": "2026-02-19T12:34:56.000000Z",
  "updatedAt": "2026-02-19T12:35:10.000000Z"
}

​
Authentication

Credit card refund webhooks are delivered with the following headers:
HeaderValue
Acceptapplication/json
Content-typeapplication/json
User-AgentWEpayments
If you have configured a custom authentication header for your account (callback authentication key and value), it will be included in every refund webhook request. Contact our support team to set up a custom authentication header so you can validate that the request was sent by WEpayments.

​
Webhook Endpoint Requirements

Your webhook endpoint must:
  • Accept POST requests - All webhook notifications are sent via POST
  • Use HTTPS - Only secure HTTPS URLs are accepted
  • Return 200 OK - Respond with a 200 status code within 5 seconds
  • Be publicly accessible - The endpoint must be reachable from the internet

​
Retry Policy

If your endpoint responds with a status code other than 200, the notification will be retried up to 15 times, with a 5-minute interval between attempts.

Create Refund

Create a refund for a credit card charge

Credit Card Webhook

Notifications about the charge status

About Credit Card

How credit card charges and refund modes work

Create Credit Card Charge

Create a new credit card charge