Merchants > API Reference > Endpoints > Deprecated Endpoints > Chargeback (Deprecated)

Chargeback (Deprecated)

This endpoint is deprecated. Send chargeback details in a Dispute Request.

Field Status Definitions

Required Required fields must be sent. If the data is not sent Ravelin will return an error.

Important Important fields are crucial for performance where that data is relevant for your business.

Optional Optional fields are additional data points that can be shared with Ravelin.
These fields are unlikely to impact performance but may be visible in the Ravelin dashboard.

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.

Show all

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.

Show definition

chargebackId string required

A unique identifier for the chargeback.

gateway string important

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.

amount integer important

The amount that is being disputed plus any chargeback penalties, in the currency's basic units.

currency string important

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.)

descriptor string optional

The billing descriptor - usually including your company name - to be shown on the payment card statement.

acquirerReferenceNumber string optional

The 23-digit reference number assigned to the transaction by the acquirer. Often abbreviated to ARN. Not available until the transaction has settled.

Pattern: ^[0-9]{23}$

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?