Dispute Transaction

Dispute

PATCH https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/trans/:tran_id/dispute

This endpoint allows you to dispute a card transaction.

Path Parameters

Name	Type	Description
tran_id	string	ID of the transaction.
node_id	string	ID of the node.
user_id	string	ID of the user.

Headers

Name	Type	Description
X-SP-USER	string	User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP	string	IP address of your device.
X-SP-GATEWAY	string	Your Client ID and Secret, separated by a pipe.

Request Body

Name	Type	Description
dispute_attachments	array of strings	Additional attachments (in base64) with the dispute form when disputing a transaction. The file types accepted are JPEG, PNG, WEBP, TIFF, BMP, GIF and PDF.
dispute_meta	string	Meta data associated with the dispute.
dispute_reason*	string	Reason for filing a dispute.

200 Subnet successfully retrieved.

{
  "dispute_form": "https://cdn.synapsepay.com/uploads/2018/10/25/z4owXU1l0xFkJ9CbtWfV7Zu53gBryLEpsKjcdPDI2qTMQ68eGO.pdf",
  "provisional_credit_tran": "5bd20bd12073c800fe748fe9",
  "success": true
}

400 Query failing

{
    "error": {
        "code": "missing_user_ip",
        "en": "User IP is missing from the request."
    },
    "error_code": "200",
    "http_code": "400",
    "success": false
}

Card Transactions

If you wish to learn more about Card Disputes, see: Card Disputes Guide.

Dispute Reason Codes

Dispute Reason Code by Network

Dispute Reason Codes are formatted as DISPUTE TYPE|DESCRIPTION.

Mastercard

Dispute Reason Code	Reason Code
FRAUD|UNAUTHORIZED|CARD_IN_HAND	4837
FRAUD|UNAUTHORIZED|CARD_LOST	4837
FRAUD|UNAUTHORIZED|CARD_IN_HAND|SHARED	4837
FRAUD|UNAUTHORIZED|CARD_IN_HAND|NOT_SHARED	4837
FRAUD|FRAUDULENT_PROCESSING_OF_TRANSACTIONS	4840
FRAUD|QUESTIONABLE_MERCHANT_ACTIVITY	4849
FRAUD|CARDHOLDER_DOES_NOT_RECOGNIZE_POTENTIAL_FRAUD	4863
FRAUD|CHIP_LIABILITY_SHIFT	4870
FRAUD|CHIP_LIABILITY_SHIFT|LOST|STOLEN|NRI	4871
	null
PROCESSING_ERROR|CORRECTION|TERMINAL_MALFUNCTION	2000
PROCESSING_ERROR|WARNING_BULLETIN_FILE	4807
PROCESSING_ERROR|AUTHORIZATION_RELATED_CHARGEBACK	4808
PROCESSING_ERROR|ACCOUNT_NUMBER_NOT_ON_FILE	4812
PROCESSING_ERROR|INCORRECT_AMOUNT	4831
PROCESSING_ERROR|CHARGED_TWICE	4831
PROCESSING_ERROR|CHARGED_TWICE|CREDIT_NOT_PROCESSED|DUPLICATE	4831
PROCESSING_ERROR|CHARGED_TWICE|CREDIT_NOT_PROCESSED|PAID_BY_OTHER_MEANS	4831
PROCESSING_ERROR|POINT_OF_INTERACTION_ERROR	4834
PROCESSING_ERROR|CANCEL_RECURRING_PMT	4841
PROCESSING_ERROR|LATE_PRESENTMENT	4842
PROCESSING_ERROR|INCORRECT_CURRENCY	4846
PROCESSING_ERROR|INSTALLMENT_BILLING_DISPUTE	4850
PROCESSING_ERROR|CHARGE_BACK	4853
PROCESSING_ERROR|ADDENDUM_NO_SHO_ATM_DISPUTE	4859
PROCESSING_ERROR|INCORRECT_AMOUNT|ATM	4859
PROCESSING_ERROR|CREDIT_NOT_PROCESSED	4860
PROCESSING_ERROR|CHIP_READ_POS_LATE_PRESENTMENT	4880
PROCESSING_ERROR|DOMESTIC_CHARGEBACK_INTRAR_EUROPEAN_USE	4999
	null
SERVICE|MERCHANT|DEFECT_OR_NOT_AS_DESC	4853
SERVICE|MERCHANT|NOT_RECEIVED	4853
SERVICE|MERCHANT|QUALITY	4853
SERVICE|MERCHANT|DAMAGED_MERCH	4853
SERVICE|MERCHANT|RETURNED_MERCH	4853
SERVICE|CARDHOLDER_DISPUTE	4853
SERVICE|CARDHOLDER_DISPUTE|NOT_ELSEWHERE_CLASSIFIED	4854
SERVICE|GOODS_OR_SERVICES_NOT_PROVIDED	4855

Maestro

Dispute Reason Code	Reason Code
FRAUD|UNAUTHORIZED|CARD_IN_HAND	37
FRAUD|UNAUTHORIZED|CARD_LOST	37
FRAUD|UNAUTHORIZED|CARD_IN_HAND|SHARED	37
FRAUD|UNAUTHORIZED|CARD_IN_HAND|NOT_SHARED	37
FRAUD|CHIP_LIABILITY_SHIFT	70
FRAUD|NO_CARDHOLDER_AUTHORIZATION	74
	null
PROCESSING_ERROR|CHARGED_TWICE	13
PROCESSING_ERROR|CASH_DISPUTE|ATM_ONLY	17
PROCESSING_ERROR|CARDHOLDER_DISPUTED_AMOUNT	30
PROCESSING_ERROR|INCORRECT_AMOUNT|ATM	31
PROCESSING_ERROR|CHARGED_TWICE|CREDIT_NOT_PROCESSED|DUPLICATE	34
PROCESSING_ERROR|CHARGED_TWICE|CREDIT_NOT_PROCESSED|PAID_BY_OTHER_MEANS	34
PROCESSING_ERROR|CANCEL_RECURRING_PMT	41
PROCESSING_ERROR|CREDIT_NOT_PROCESSED	60
PROCESSING_ERROR|INCORRECT_AMOUNT	71
PROCESSING_ERROR|DUPLICATE_TRANSACTION	73
PROCESSING_ERROR|CREDIT_NOT_RECEIVED	75
PROCESSING_ERROR|LATE_PRESENTMENT	80
PROCESSING_ERROR|INVALID_ADJUSTMENT_AMOUNT	95
PROCESSING_ERROR|INVALID_ADJUSTMENT_AMOUNT|INSUFFICIENT_FUNDS	96
	null
SERVICE|CHARGE_BACK	53
SERVICE|MERCHANT|QUALITY	53
SERVICE|MERCHANT|DAMAGED_MERCH	53
SERVICE|MERCHANT|RETURNED_MERCH	53
SERVICE|MERCHANT|DEFECT_OR_NOT_AS_DESC	53
SERVICE|NON_RECEIPT_OF_MERCHANDISE	55
SERVICE|MERCHANT|NOT_RECEIVED	79

Pulse

Dispute Reason Code	Reason Code
FRAUD|UNAUTHORIZED|CARD_IN_HAND	4537
FRAUD|UNAUTHORIZED|CARD_LOST	4537
FRAUD|UNAUTHORIZED|CARD_IN_HAND|SHARED	4537
FRAUD|UNAUTHORIZED|CARD_IN_HAND|NOT_SHARED	4537
FRAUD|CARD_PRESENT_TRANSACTION	4537
FRAUD|UNAUTHORIZED_PURCHASE	4540
FRAUD|CHARGE_BACK	4752
FRAUD|CHIP_CARD_COUNTERFEIT_TRANSACTION	4866
FRAUD|CHIP_CARD_AND_PIN_TRANSACTION	4867
FRAUD|CARD_NOT_PRESENT_TRANSACTION	4868
	null
PROCESSING_ERROR|CORRECTION|TERMINAL_MALFUNCTION	2000
PROCESSING_ERROR|INVALID_CARDHOLDER_NUMBER	4512
PROCESSING_ERROR|DUPLICATE_PROCESSING	4534
PROCESSING_ERROR|CANCEL_RECURRING_PMT	4541
PROCESSING_ERROR|AUTHORIZATION|LATE_PRESENTMENT	4542
PROCESSING_ERROR|INCORRECT_TRANSACTION_TYPE	4550
PROCESSING_ERROR|CREDIT_NOT_PROCESSED	4560
PROCESSING_ERROR|ALTERED_AMOUNT	4586
PROCESSING_ERROR|INCORRECT_AMOUNT	4586
PROCESSING_ERROR|NON_RECEIPT_OF_CASH_FROM_ATM	4590
PROCESSING_ERROR|CHARGED_TWICE	4831
PROCESSING_ERROR|CHARGED_TWICE|CREDIT_NOT_PROCESSED|DUPLICATE	4831
PROCESSING_ERROR|CHARGED_TWICE|CREDIT_NOT_PROCESSED|PAID_BY_OTHER_MEANS	4831
PROCESSING_ERROR|INCORRECT_AMOUNT|ATM	4859
PROCESSING_ERROR|PAID_BY_OTHER_MEANS	4865
	null
SERVICE|QUALITY_OF_GOODS_AND_SERVICES	4553
SERVICE|NON_RECEIPT_OF_GOODS_AND_SERVICE	4555
SERVICE|MERCHANT|NOT_RECEIVED	4853
SERVICE|MERCHANT|QUALITY	4853
SERVICE|MERCHANT|DAMAGED_MERCH	4853
SERVICE|MERCHANT|RETURNED_MERCH	4853

Legacy Dispute Reason Lookup

Below is the table of legacy dispute reason codes.

Code	Description	Chargeback‎_Rights
INCORRECT_AMOUNT	Incorrect Amount was charged on the card.	Yes. No if the transaction is a VALID EMV transaction.
INCORRECT_AMOUNT|ATM	User attempted to withdraw money from ATM and received incorrect amount.	Yes, but only for the amount not dispensed.
UNAUTHORIZED|CARD_LOST	Unauthorized transaction made and user has reported a lost or stolen card.	Yes. No if the transaction is a VALID EMV transaction or online transaction as this defaults to chip-liability shift, which is not applicable to MOTO transactions, or at an ATM.
UNAUTHORIZED|CARD_IN_HAND|SHARED	Unauthorized transaction made while user has card in their possession and card is shared with other users.	Yes. No if the transaction is a VALID EMV transaction, or disputed transactions was authorized by other users of the card, or at an ATM.
UNAUTHORIZED|CARD_IN_HAND|NOT_SHARED	Unauthorized transaction made while user has card in their possession and card is not shared with other users.	Yes. No if the transaction is a VALID EMV transaction, or at an ATM.
CHARGED_TWICE|CREDIT_NOT_PROCESSED|DUPLICATE	There was a duplicate transaction but the merchant did not process a credit to correct the error. This typically occurs when when a merchant a merchant fails to correct a previously acknowledged error. This can also occur when a cardholder attempts to return a purchased item or cancel services but is not compliant with the merchant's return policy (e.g. expired receipt or warranty issue).	Yes. No if the transaction is a VALID EMV transaction, or no duplicate posts to same account.
CHARGED_TWICE|CREDIT_NOT_PROCESSED|PAID_BY_OTHER_MEANS	There was a duplicate transaction in which the original debit settled on the card even though the original card transaction was canceled. Occurs when the cardholder chose to use another payment method (e.g. cash or a different card).	Yes. No if the transaction is a VALID EMV transaction, or there is not supporting evidence of a charge elsewhere.
CANCEL_RECURRING_PMT	Canceling recurring payment (i.e. a recurring payment was debited after cancellation).	Yes. No if the transaction is a VALID EMV transaction, or cancellation was within three days of charge authorization.
MERCHANT|DEFECT_OR_NOT_AS_DESC	Merchandise/service not as described or defective merchandise/service.	Yes. No if the transaction is a VALID EMV transaction.
MERCHANT|NOT_RECEIVED	Did not receive merchandise or services (not a quality issue).	Yes. No if the transaction is a VALID EMV transaction, or if merchant hasn't been allowed 15 calendar days for items to arrive or to provide a date of expected arrival.
MERCHANT|QUALITY	Issue with quality of services or merchandise.	Yes. No if the transaction is a VALID EMV transaction, or services were paid for after service was rendered.
MERCHANT|DAMAGED_MERCH	Damaged merchandise.	Yes. No if the transaction is a VALID EMV transaction.
MERCHANT|RETURNED_MERCH	Returned merchandise.	Yes. No if the transaction is a VALID EMV transaction, or there is no supporting evidence of a return.
FRAUD|FRAUDULENT_PROCESSING_OF_TRANSACTIONS	Authorized card-present transaction with a merchant but received additional non-authorized transactions within the following fifteen minutes.	Yes. No if proof can be provided that a refund was issued or provide evidence that additional transactions are authorized.
FRAUD|QUESTIONABLE_MERCHANT_ACTIVITY	Merchant is suspected of fraud by Mastercard, and has been placed under the Global Merchant Audit Program.	Yes. No if merchant is not on Global Merchant Audit Program.
FRAUD|CARDHOLDER_DOES_NOT_RECOGNIZE_POTENTIAL_FRAUD	User claims they do not recognize a transaction and the transaction is a Card-not-Present transaction	Yes. No if merchant can verify the card was present for transaction.
FRAUD|AUTHORIZATION_RELATED_CHARGEBACK	Merchant did not get authorization for a transaction, or authorization was sent after the transaction date.	Yes. No if proof can be provided that authorization was obtained and authorization date request was not after the transaction date.

Dispute Meta

Currently Dispute Meta is only required for Card Transaction. Following are the fields allowed in dispute_meta:

Key	Type	Required Dispute Reasons	Description
amount_debited	Float	INCORRECT_AMOUNT	Amount debited in Number.
amount_received	Float	INCORRECT_AMOUNT|ATM	Amount received in Number.
lost_date	Int	UNAUTHORIZED|CARD_LOST	Date lost (milliseconds since Unix epoch time).
how_lost	String	UNAUTHORIZED|CARD_LOST	Description of how card was lost or stolen.
last_use	String	UNAUTHORIZED|CARD_IN_HAND|SHARED UNAUTHORIZED|CARD_IN_HAND|NOT_SHARED	Transaction ID for last use of card (i.e. need transaction ID to know where and when card was last used).
people_allowed_use	String	UNAUTHORIZED|CARD_IN_HAND|SHARED	Person(s) who cardholder shared card with (i.e. allowed to use card) and their relationship(s) with cardholder.
contact_date	Object with $date attribute	CANCEL_RECURRING_PMT	Contact date (milliseconds since Unix epoch time).
contact_method	String	CANCEL_RECURRING_PMT	Contact method (e.g. PHONE).
trans_on_same_card	Boolean	CHARGED_TWICE|CREDIT_NOT_PROCESSED|DUPLICATE CHARGED_TWICE|CREDIT_NOT_PROCESSED|PAID_BY_OTHER_MEANS	Are both transactions on the same card? true or false. Proof of other transaction required in dispute_attachments
merch_given_attempt_to_resolve	Boolean	CHARGED_TWICE|CREDIT_NOT_PROCESSED|DUPLICATE CHARGED_TWICE|CREDIT_NOT_PROCESSED|PAID_BY_OTHER_MEANS MERCHANT|RETURNED_MERCH	Was the merchant given the chance to resolve? true or false.
contact_name	String	CANCEL_RECURRING_PMT	Name of contact.
contact_response	String	CANCEL_RECURRING_PMT	Response from contact.
merch_item_desc	String	MERCHANT|DEFECT_OR_NOT_AS_DESC MERCHANT|RETURNED_MERCH	Description of the merchandise
date_received	Int	MERCHANT|DEFECT_OR_NOT_AS_DESC	Date merchandise/item was received
matched_verbal_or_written_desc	Boolean	MERCHANT|DEFECT_OR_NOT_AS_DESC	Did the item or service not match the verbal description
matched_receipt_desc	Boolean	MERCHANT|DEFECT_OR_NOT_AS_DESC	Did the item or service differ from as described on the receipt
merchandise_received_as_part_of_transaction	Boolean	MERCHANT|DEFECT_OR_NOT_AS_DESC	Was Merchandise Received as Part of Transaction
order_canceled	Boolean	MERCHANT|NOT_RECEIVED MERCHANT|RETURNED_MERCH	Was the order canceled
expected_arrival_date	Int	MERCHANT|NOT_RECEIVED	Date when it was expected to arrive
was_item_delivered	Boolean	MERCHANT|NOT_RECEIVED	Was item delivered
prepaid_item	Boolean	MERCHANT|NOT_RECEIVED	Was this item a prepaid item
recurring_payment	Boolean	MERCHANT|RETURNED_MERCH	Was this a recurring payment
merch_returned	Boolean	MERCHANT|RETURNED_MERCH	Was the merchandise returned
merch_returned_attempted	Boolean	MERCHANT|RETURNED_MERCH	Was the merchandise attempted to be returned
reason	String	MERCHANT|RETURNED_MERCH	Reason for Return or cancelation
cancel_policy_provided	Boolean	MERCHANT|RETURNED_MERCH	Was a cancelation Policy provided

ACH Transactions

Dispute Reasons

Code	Description
R07	Authorization Revoked by Customer
R08	Payment Stopped
R10	Customer Advises Not Authorized
R29	Corporate Customer Advises Not Authorized
R23	Credit Refused by Receiver

Example Request

HTTP

PATCH /v3.1/users/605a7a6a7562967ff8c12413/nodes/605125f47e08875d713557ed/trans/6045135016ba41408ece9c25/dispute HTTP/1.1
Host: uat-api.synapsefi.com
X-SP-USER-IP: 255.127.79.76
X-SP-USER: oauth_xg3WXDFu5jNRLlz1ohf6qsU0waJ4BGYbMdrC07pO|e83cf6ddcf778e37bfe3d48fc78a6502062fc
Content-Type: application/json

{
  "dispute_reason": "CHARGE_BACK",
  "dispute_meta": {
    "type_of_merchandise_or_service": "groceries",
    "merchant_contacted": true,
    "contact_method": "phone",
    "contact_date": 1563474864000
  },
  "dispute_attachments": [
    "data:image/gif;base64,SUQs=="
  ]
}

cURL

curl --location --request PATCH 'https://uat-api.synapsefi.com/v3.1/users/605a7a6a7562967ff8c12413/nodes/605125f47e08875d713557ed/trans/6045135016ba41408ece9c25/dispute' \
--header 'X-SP-USER-IP: 255.127.79.76' \
--header 'X-SP-USER: oauth_xg3WXDFu5jNRLlz1ohf6qsU0waJ4BGYbMdrC07pO|e83cf6ddcf778e37bfe3d48fc78a6502062fc' \
--header 'Content-Type: application/json' \
--data-raw '{
  "dispute_reason": "CHARGE_BACK",
  "dispute_meta": {
    "type_of_merchandise_or_service": "groceries",
    "merchant_contacted": true,
    "contact_method": "phone",
    "contact_date": 1563474864000
  },
  "dispute_attachments": [
    "data:image/gif;base64,SUQs=="
  ]
}'

Python

//

JS

//

PHP

//

GO

//