This endpoint is deprecated. Send chargeback details in a Dispute Request.
POST
/v2/chargeback
A chargeback happens when a customer disputes a payment on their credit card
account. Communicate this event to Ravelin using the chargeback endpoint. This
is a mandatory component of all integrations. Our ability to predict fraud comes
from our understanding of previous examples of fraudulent behaviour.
Most PSPs will associate two IDs with every chargeback: a unique identifier for
the chargeback itself, and the identifier for the original transaction that is
being disputed. It is the latter that must be sent in the gatewayReference
field, and it should correspond to a previously sent transaction.
For PSPs that associate chargebacks via the Merchant transaction ID, such as
Computop, the transactionId can be specified in lieu of the gatewayReference.
If only the original order ID is known, Ravelin will guess that the first
successful auth, capture, or auth_capture transaction is the charge being
disputed.
If no transaction with a matching orderId, gatewayReference or
transactionId is found, this chargeback is ignored.
timestamp
integer
required
The time at which this data payload was valid. When sending events in realtime, this will usually be 'now'. This is used to merge data that arrives out-of-order.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
chargeback
object
required
The chargeback coming from a fraudulent claim filed with the cardholder's
issuer.
The gateway that the originating transaction was processed by.
gatewayReference
string
important
The PSP/gateway's reference for the transaction which was disputed.
Should match the gateway and reference fields supplied on the
transaction object. Not required if you supply transactionId.
transactionId
string
important
A reference to the transaction being disputed. Should match the
transactionId supplied on the transaction object. Not required if you
supply a gatewayReference.
The currency of the amount of this chargeback, as an ISO 4217 currency code.
Pattern: ^[a-zA-Z]{3}$
disputeTime
integer
important
The time that the dispute that lead to this chargeback was opened.
Used in reporting.
A unix timestamp preferably as an
integer count of milliseconds since 1970-01-01T00:00 UTC
(nanoseconds are also accepted).
reason
string
optional
The reason code from the chargeback.
status
string
optional
The status of the dispute. Preferably one of:
OPEN: No action has been taken yet.
ACCEPTED: You have opted out of providing evidence against the chargeback or pre-arb.
DISPUTED: You have submitted evidence against the claim and are waiting for the decision from the bank.
LOST: The bank has not ruled in your favour, the funds will be returned to the cardholder, and you will pay a chargeback penalty.
WON: The bank has ruled in your favour, and you will keep the funds originally collected from the card.
EXPIRED: The date to submit evidence has passed and you have forfeited your right to dispute the case.
See notifications of fraud for sending TC-40s,
Ethoca Alerts and other early notifications.
liabilityShifted
boolean
optional
Whether liability for this chargeback was shifted to a third-party,
such as your PSP or gateway.
(See Liability shift.)
nonFraud
boolean
optional
Whether this chargeback was claimed for reasons other than fraud. If
this chargeback was not filed for reasons of fraud (e.g. goods not as
described) then be sure to set a reason. (See non-fraudulent chargebacks.)
custom
object
optional
Custom data that is relevant to your domain. This can be any json object.
Please include any details that you think are relevant to fraud that our
schema does not capture.
eventType
string
optional
An eventType should identify what event in your system triggered this API call.
Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]*$
orderId
string
optional
The ID of the order the chargeback originated from. When provided
instead of gatewayReference and transactionId, Ravelin will set the
gatewayReference and transactionId to that of the first successful
transaction of the order.
customerId
string
optional
The ID of the customer this chargeback originated from.
Ravelin will look this up from the referenced order or transaction.
Feedback
Was this page helpful?
Thanks for the feedback.
If you'd like to provide more detail you can share it in our Help Center.