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.

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.

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.

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.

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

{
    "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

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

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 --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=="
  ]
}'

//

//

//

//

PreviousDispute Chargebacks NextSubscriptions

Last updated 11 months ago