Onerway
POST

Chargeback alert webhook

View as Markdown
Webhook URL
Receive chargeback alerts at the configured chargeback alert webhook URL. Return the received predisputeId unchanged to acknowledge the notification.

Signature coverage

Request signing guide

All payload fields are included in the signature except:

  • sign(legacy signature value)

Webhook payload fields

notifyTypestring
Notification type, fixed to PRE_DISPUTE.
Allowed values
PRE_DISPUTE
Chargeback alert.
transactionIdstring
Onerway alert ID, identical to predisputeId. This is not the original payment transaction ID.
merchantNostring
Merchant number assigned by Onerway.
predisputeIdstring
Unique ID of the chargeback alert. Return this value unchanged in the acknowledgement body.
timeZonestring
Time zone offset reported with the notification. This field may be absent.
servicestring
Alert service. Returned when service visibility is enabled for the merchant and the value is available; otherwise it may be absent.
typestring
Alert type. Returned when type visibility is enabled for the merchant and the value is available; otherwise it may be absent.
createdTimestring
Time when the alert was raised, in yyyy-MM-dd HH:mm:ss format.
receivedTimestring
Time when the alert was successfully matched to a transaction, in yyyy-MM-dd HH:mm:ss format. This field may be absent if no matching time is available.
amountstring
Alert refund amount in currency, expressed as a decimal string with two decimal places. Uses the remaining refundable amount when available; otherwise uses the alert amount. It may differ from orderAmount.
currencystring
Currency of amount: the currency of the alert refund amount when available, otherwise the alert currency.
sourcestring
Party that raised the alert. This field may be absent when unavailable.
reasonCodestring
Reason code for the alert. This field may be absent when unavailable.
txnIdstring
Original Onerway payment transaction ID. This field may be absent when the original transaction details are unavailable.
merchantTxnIdstring
Merchant order number of the original payment. This field may be absent when the original transaction details are unavailable.
txnTimestring
Creation time of the original transaction, in yyyy-MM-dd HH:mm:ss format. This field may be absent when the original transaction details are unavailable.
orderAmountstring
Original order amount in orderCurrency, expressed as a decimal string with two decimal places. This field may be absent when the original transaction details are unavailable.
orderCurrencystring
Currency of the original order amount. This field may be absent when the original transaction details are unavailable.
paymentMethodstring
Payment method or card brand of the original transaction. This field may be absent when the original transaction details are unavailable.
ecistring
Electronic Commerce Indicator (ECI) of the original transaction. This field may be absent when the original transaction details are unavailable.
websitestring
Website where the cardholder made the original transaction. This field may be absent when the original transaction details are unavailable.
emailstring
Email address associated with the original transaction. This field may be absent when the original transaction details are unavailable.
chargebackStatusstring
Whether the matched transaction has a chargeback. This field may be absent when unavailable; it is not a chargeback lifecycle status.
Allowed values
0
No chargeback.
1
Has a chargeback.
refundStatusstring
Refund status of the matched transaction. This field may be absent when unavailable.
Allowed values
0
Not refunded.
1
Fully refunded.
2
Partially refunded.
signstringSignature field · Excluded from signature
Signature included in the notification body. This field is excluded from signature calculation. Verify the notification using the X-Rh-Signature header as described in the signing guide.

Webhook example

{
  "notifyType": "PRE_DISPUTE",
  "transactionId": "example_predispute",
  "merchantNo": "example_merchant",
  "predisputeId": "example_predispute",
  "type": "customerdispute_alert",
  "createdTime": "2026-09-17 22:59:37",
  "receivedTime": "2026-09-17 22:59:40",
  "amount": "10.00",
  "currency": "USD",
  "txnId": "example_payment",
  "merchantTxnId": "example_order",
  "txnTime": "2026-07-27 18:10:59",
  "orderAmount": "11.00",
  "orderCurrency": "USD",
  "paymentMethod": "VISA",
  "chargebackStatus": "0",
  "refundStatus": "2",
  "eci": "5",
  "website": "example.com",
  "email": "buyer@example.com",
  "sign": "replace_with_signature"
}

Acknowledgement

After accepting the notification, return HTTP 200 with the received predisputeId unchanged in the response body. Do not add JSON quotes, whitespace, or a newline. An empty response or a different ID is not accepted. On failure or an invalid response, Onerway retries every 30 minutes, up to 2 times.

Response body example

HTTP 200
Return the received predisputeId unchanged. Do not return the fixed example value.
example_predispute

Refund request rejection webhook

Sent to the original transaction’s notifyUrl only when Onerway rejects a refund request during review (notifyType=REFUND_AUDIT).

Chargeback status change webhook

Reports chargeback status changes without retries.