Merchants > API Reference > Endpoints > Dispute

Dispute

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.

Jump to Response

POST api.ravelin.com/v2/dispute

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

dispute object required

A dispute occurs when a cardholder makes a claim to the issuer of their payment method to challenge the legitimacy of a payment, initiating a chargeback for card payment methods. See our Sending Disputes guide to learn more about the dispute process.

Show definition

disputeId string required

Unique identifier for the dispute.

stage string required

Stage of the dispute. A dispute with the stage EARLY_FRAUD_WARNING or REQUEST_FOR_INFORMATION is not considered a chargeback for reporting purposes. See our Sending Disputes guide to learn more.

One of: EARLY_FRAUD_WARNING, REQUEST_FOR_INFORMATION, NOTIFICATION_OF_CHARGEBACK, CHARGEBACK, SECOND_CHARGEBACK, CHARGEBACK_REVERSED, PREARBITRATION, or ARBITRATION.

gateway string important

Name of the payment gateway that processed the disputed transaction.

gatewayReference string important

Payment gateway's identifier for the disputed transaction. Must match the gateway reference of the original transaction. Not required if you provide transactionId.

transactionId string important

Identifier for the disputed transaction. Must match the transaction identifier of the original transaction. Not required if you provide gatewayReference.

amount integer important

Disputed amount, in the currency's basic units, including any additional dispute fees or penalties.

currency string important

Currency of the dispute amount, as an ISO 4217 currency code.

Pattern: ^[a-zA-Z]{3}$

disputeTime integer important

Time at which the dispute was created, used for reporting. A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

reason string optional

Reason given by the cardholder for disputing the transaction.

outcome string optional

Outcome of the dispute. Use ACCEPTED for disputes you have accepted and decided not to defend, WON for disputes you have successfully defended, EXPIRED for disputes that have timed out and LOST for disputes ruled in favour of the cardholder. Omit outcome if the dispute is still open.

One of: ACCEPTED, WON, LOST, or EXPIRED.

liabilityShifted boolean optional

Whether liability for this dispute was shifted to the issuer. See Liability Shift.

nonFraud boolean optional

Whether the cardholder disputed the payment for reasons other than fraud. Make sure to set a reason if this is the case - see our disputes guide to learn more.

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 dispute 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 dispute originated from. Ravelin will look this up from the referenced order or transaction.

POST https://api.ravelin.com/v2/dispute HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "dispute": {
    "disputeId": "abc-123-XYZ",
    "gateway": "braintree",
    "gatewayReference": "abc-123-XYZ",
    "transactionId": "abc-123-XYZ",
    "amount": 15212,
    "currency": "GBP",
    "disputeTime": 1479302798,
    "reason": "fraud",
    "stage": "CHARGEBACK",
    "outcome": "LOST",
    "liabilityShifted": true,
    "nonFraud": false,
    "descriptor": "ravelin.com #1239424",
    "acquirerReferenceNumber": "12345678901234567890123"
  }
}

Response

Show all

status integer optional

The HTTP response status code.

timestamp integer optional

A Unix timestamp indicating when we finished handling the request.

data object optional

Contains details related to the dispute.

Show definition

warnings array optional

Warnings when the data in the request contained issues.

See API Warnings for more information.

Show definition

class string optional

Identifier for this warning. Format is [a-z-]+ so you can safely record it in your metrics system.

help string optional

A link to more information about this class of warning and the impact of not resolving.

msg string optional

A description indicating why this warning has been issued.

{
  "status": 200,
  "timestamp": 1512828988826,
  "data": {
    "warnings": [
      {
        "class": "customer-not-found",
        "help": "https://developer.ravelin.com/api/warnings/#customer-not-found",
        "msg": "Customer \"abc-123-ZYZ\" not found."
      }
    ]
  }
}

Feedback

Was this page helpful?