Onerway
POST

Ethoca alert webhook

View as Markdown
Webhook URL
Use this webhook to receive Ethoca alert notifications and link each alert back to the original transaction through ethocaId and transactionId.

Webhook payload fields

idnumber
Onerway alert notification record ID, used to locate this alert notification record.
Constraints
Rule
This value is a large integer. JavaScript systems should preserve it as a string or 64-bit integer to avoid precision loss.
merchantNostring
Merchant number assigned by Onerway, identifying the merchant account receiving this alert.
Constraints
Rule
The notification can return this value as a JSON number. Normalize it as a string before storing or comparing it with other Onerway API values.
ethocaIdstring
Unique Ethoca alert identifier. Submit this value when reporting the alert outcome.
alertTypestring
Alert type indicating whether this notification is a customer dispute alert, fraud alert, or chargeback alert.
Allowed values
CustomerDispute
Customer dispute alert.
FraudAlert
Fraud alert.
ChargebackAlert
Chargeback alert.
alertTimestring
Alert creation time in yyyy-MM-dd HH:mm:ss format.
alertAgenumber
Elapsed time between alert creation and this notification. Use it to assess alert age and handling priority.
Constraints
Rule
The unit is hours.
txnTimestring
Original transaction time in yyyy-MM-dd HH:mm:ss format.
txnAmountnumber
Original transaction amount.
txnCurrencystring
Original transaction currency, using a three-letter ISO 4217 currency code.
resellerSubMerchantIdstring
Agency sub-merchant identifier.
billDescstring
Merchant billing descriptor used to match the alert to merchant information shown on the cardholder statement.
arnstring
Acquirer Reference Number (ARN), used for reconciliation, alert review, and dispute handling.
submitOutcomeStatusstring
Alert outcome submission status. Do not treat this field as the final outcome value.
Allowed values
PENDING_OUTCOME
Pending outcome. The alert is still waiting for outcome submission.
OUTCOME_RECEIVED
Outcome received. The alert outcome has been accepted.
outcomestring
Merchant outcome for this alert.
Allowed values
stopped
Order stopped.
partially_stopped
Order partially stopped.
previously_cancelled
Transaction previously cancelled.
outcomeUpdatedTimestring
Alert outcome update time in yyyy-MM-dd HH:mm:ss format.
refundStatusstring
Refund status corresponding to this alert outcome.
Allowed values
refunded
Refund completed.
not refunded
No refund was issued.
not settled
Refund is processing.
createOprstring
Record metadata: identifier of the account or system that created the alert record. Do not use this field to determine alert status or required business action.
createTimestring
Alert record creation time in Onerway in yyyy-MM-dd HH:mm:ss format.
updateOprstring
Record metadata: identifier of the account or system that most recently updated the alert record. Do not use this field to determine alert status or required business action.
updateTimestring
Most recent alert record update time in Onerway in yyyy-MM-dd HH:mm:ss format.
issuerstring
Issuer identifier. The value format is returned by the alert network.
cardNumberstring
Card number information associated with the alerted transaction.
Constraints
Rule
If the payload contains a full PAN, handle it according to PCI DSS requirements and avoid storing it in logs, support tickets, or ordinary databases.
ethocaMerchantIdstring
Ethoca merchant identifier, used in the Ethoca alert network to match merchants and billing descriptors.
mccstring
Merchant Category Code (MCC), usually a four-digit code.
transactionTypestring
Original transaction type or transaction scenario.
Example:eCommerce
initiatedBystring
Alert initiator, usually a card network, issuer, or alert network identifier.
liabilitystring
Liability marker related to the alert or dispute. Treat it as supporting information, not a replacement for reviewing alertType, outcome, and refund status.
authCodestring
Authorization code of the original transaction, usually returned by the issuer or acquiring network after successful authorization.
integratorMemberIdstring
Integrator member ID identifying the integration relationship on the alert network side.
transactionIdstring
Original Onerway transaction ID used to associate transaction query, refund, chargeback, and alert outcome records.
chargebackReasonCodestring
Chargeback or dispute reason code provided by the card network or alert network.
chargebackAmountnumber
Chargeback or dispute amount associated with the alert. It can be less than or equal to the original transaction amount.
chargebackCurrencystring
Chargeback or dispute amount currency, using a three-letter ISO 4217 currency code.

Webhook example

{
  "id": 1234567890,
  "merchantNo": "replace_with_merchant_no",
  "ethocaId": "replace_with_ethoca_id",
  "alertType": "ChargebackAlert",
  "alertTime": "2025-04-14 14:26:21",
  "alertAge": 12,
  "txnTime": "2025-04-13 09:15:00",
  "txnAmount": 100,
  "txnCurrency": "USD",
  "resellerSubMerchantId": null,
  "billDesc": "DEMO STORE",
  "arn": "replace_with_acquirer_reference_number",
  "submitOutcomeStatus": "PENDING_OUTCOME",
  "outcome": null,
  "outcomeUpdatedTime": null,
  "refundStatus": null,
  "createOpr": "SYSTEM",
  "createTime": "2025-04-14 14:26:21",
  "updateOpr": "SYSTEM",
  "updateTime": "2025-04-14 14:26:21",
  "issuer": "replace_with_issuer_identifier",
  "cardNumber": "replace_with_card_number",
  "ethocaMerchantId": "replace_with_ethoca_merchant_id",
  "mcc": "5812",
  "transactionType": "eCommerce",
  "initiatedBy": "replace_with_alert_initiator",
  "liability": "no",
  "authCode": "replace_with_authorization_code",
  "integratorMemberId": "replace_with_integrator_member_id",
  "transactionId": "replace_with_transaction_id",
  "chargebackReasonCode": "4837",
  "chargebackAmount": 100,
  "chargebackCurrency": "USD"
}

Acknowledgement

Return HTTP 200 after the webhook is received and accepted.

Response body example

HTTP 200

No response body.

Fraud alert webhook

Receive fraud alert payloads with the fraud type, original transaction, chargeback flag, and refund status.

Payment result webhook

Receive ordinary payment result notifications for successful, failed, timed-out, or canceled payment flows.