Flag Chargeback

Flag Chargeback is essential for calibrating the accuracy of our risk analysis.

Flag Chargeback

Request Example

POST {ENDPOINT}/v1/chargeback

REQUEST HEADER
Content-Type: application/json
Authorization: Bearer {TOKEN}
X-Api-Version: v2

REQUEST BODY (see field descriptions)
{
"code": "{Order code}",
"message": "Example message",
"chargebackStatus": 1,
"chargebackDateUTC": "{Chargeback notification date by the acquirer}",
"reasonCode": "{Chargeback request reason code}",
"disputeReason": 1,
"bin": "123456",
"pan": "123456",
"cardBrandId": "3",
"cardBrand": "VISA",
"disputeValue": 100.00,
"cardOwnerName": "{Credit Card Holder's Name}",
"shippingStatus": 0,
"nsu": "{Sale operation identification number}",
"tid": "{Transaction ID of the sale}",
"psp": "{Dispute identification number}"
}

Response Example

RESPONSE HEADER

Content-Type: application/json
Request-ID: {"REQUEST_ID_OF_THE_REQUEST"}

RESPONSE BODY
{
"code": "{MY_ORDER_CODE}",
"status": "Chargeback done",
"errors": null
}

Table of Codes and Descriptions

Credit Card Brand (cardBrandId and cardBrand)

Code	Description
1	Diners
2	MasterCard
3	Visa
4	Others
5	American Express
6	HiperCard
7	Aura Card
10	Elo Card

JSON Field Descriptions for Flag Chargeback

Property	Description	Type	Size	Required
code	Order ID (same value previously sent in the "transactionId" or "code" property of the order risk analysis JSON, depending on the API endpoint used for this submission).	String	50	S
message	Message
chargebackStatus	0 - for "Pre-Chargeback", 1 - for "Chargeback Debit" (default value)	Integer		N
chargebackDateUTC	Chargeback notification date by the acquirer	Datetime		S
reasonCode	Chargeback request reason code	String	100	N
disputeReason	Dispute Reason: 0 - for "Commercial Disagreement", 1 - for "Fraud", 2 - for "Processing Error"	Integer		N
bin	First 6 digits of the credit card	String	50	N
pan	Alternative field to the card bin, which has this name in some cases. First 6 digits of the card.	String	50	N
cardBrandId	Credit card brand ID	Integer		N
cardBrand	Description of the credit card brand	String	50	N
disputeValue	Chargeback Value	Decimal	20,4	N
cardOwnerName	Credit Card Holder's Name	String	200	N
shippingStatus	Purchase delivery status: 0 - for "Delivered", 1 - for "Delivery Blocked", 2 - for "In route for Return"	Integer		N
nsu	Sale operation identification number	String	200	N
tid	Transaction ID of the sale	String	200	N
psp	Dispute identification number	String	100	N

API Error Returns for Flag Chargeback

Invalid or expired token

HTTPCode: 401 Unauthorized

Body: {Empty}

Request without the "code" property

HTTPCode: 400 Bad Request

Body:
{
  "code": "{Order code}",
  "status": "Fail",
  "errors": [
    "Code: Required field"
  ]
}

Request without the "chargebackDateUTC" property

HTTPCode: 400 Bad Request

Body:
{
  "code": "{Order code}",
  "status": "Fail",
  "errors": [
    "ChargebackDateUTC: Required field"
  ]
}

Value of the "code" property exceeded the character limit

HTTPCode: 400 Bad Request

Body:
{
  "code": "{Order code}",
  "status": "Fail",
  "errors": [
    "Code: Exceeded maximum size of 50 characters."
  ]
}

Value of the "message" property exceeded the character limit

HTTPCode: 400 Bad Request

Body:
{
  "code": "{Order code}",
  "status": "Fail",
  "errors": [
    "Message: Exceeded maximum size of 100 characters."
  ]
}

Value of the "reasonCode" property exceeded the character limit

HTTPCode: 400 Bad Request

Body:
{
  "code": "{Order code}",
  "status": "Fail",
  "errors": [
    "ReasonCode: Exceeded maximum size of 100 characters."
  ]
}

Value of the "bin" property exceeded the character limit

HTTPCode: 400 Bad Request

Body:
{
  "code": "{Order code}",
  "status": "Fail",
  "errors": [
    "Bin: Exceeded maximum size of 50 characters."
  ]
}

Value of the "pan" property exceeded the character limit

HTTPCode: 400 Bad Request

Body:
{
  "code": "{Order code}",
  "status": "Fail",
  "errors": [
    "Pan: Exceeded maximum size of 50 characters."
  ]
}

Value of the "cardBrand" property exceeded the character limit

HTTPCode: 400 Bad Request

Body:
{
  "code": "{Order code}",
  "status": "Fail",
  "errors": [
    "cardBrand: Exceeded maximum size of 200 characters."
  ]
}

Value of the "disputeValue" property exceeded the character limit

HTTPCode: 400 Bad Request

Body:
{
  "code": "{Order code}",
  "status": "Fail",
  "errors": [
    "DisputeValue: Must be greater than or equal to 0."
  ]
}

Value of the "nsu" property exceeded the character limit

HTTPCode: 400 Bad Request

Body:
{
  "code": "{Order code}",
  "status": "Fail",
  "errors": [
    "NSU: Exceeded maximum size of 200 characters."
  ]
}

Value of the "tid" property exceeded the character limit

HTTPCode: 400 Bad Request

Body:
{
  "code": "{Order code}",
  "status": "Fail",
  "errors": [
    "TID: Exceeded maximum size of 200 characters."
  ]
}

Value of the "psp" property exceeded the character limit

HTTPCode: 400 Bad Request

Body:
{
  "code": "{Order code}",
  "status": "Fail",
  "errors": [
    "PSP: Exceeded maximum size of 200 characters."
  ]
}

Invalid "shippingStatus" value

HTTPCode: 400 Bad Request

Body:
{
  "code": "{Order code}",
  "status": "Fail",
  "errors": [
    "ShippingStatus: Not a valid ShippingStatus."
  ]
}

Order status in ClearSale does not allow chargeback marking at the moment

HTTPCode: 422 Unprocessable Entity

Body:
{
  "code": "{Order code}",
  "status": "Fail",
  "errors": [
    "Cannot mark the chargeback, please check its status."
  ]
}

Request with empty body

HTTPCode: 500 Internal Server Error

Body:
{Empty}

Error with unmapped cause (ClearSale analysis required)

HTTPCode: 500 Internal Server Error

Body:
{
  "code": "{Order code}",
  "status": "Fail",
  "errors": [
    "An error occurred while trying to mark the Chargeback."
  ]
}

Duplicate chargeback marking for the same order within less than 1 minute difference

HTTPCode: 202 Accepted

Body:
{
"code": "{Order code}",
"status": "Chargeback is being processed.",
"errors": null
}