GuidesAPI RefFAQsBlog
API Ref
StatusSupport

Dispute Transaction

patch https://uat-api.synapsefi.com/v3.1/users//nodes//trans//dispute#

Reg E Request Body

Key ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌  ‌ ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌TypeDescription
dispute_reasonstring[Required for all disputes] Reason you are disputing the transaction. See the list of dispute reasons below for more information
dispute_meta.amount_debitedinteger[Required for INCORRECT_AMOUNT] Amount debited.
dispute_meta.amount_receivedinteger[Required for INCORRECT_AMOUNT|ATM] Amount received.
dispute_meta.lost_dateinteger[Required for UNAUTHORIZED|CARD_LOST] Date lost (milliseconds since Unix epoch time).
dispute_meta.how_loststring[Required for UNAUTHORIZED|CARD_LOST] Description of how card was lost or stolen.
dispute_meta.last_usestring[Required for UNAUTHORIZED|CARD_IN_HAND|SHARED and 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).
dispute_meta.people_allowed_usestring[Required for UNAUTHORIZED|CARD_IN_HAND|SHARED] Person(s) who cardholder shared card with (i.e. allowed to use card) and their relationship(s) with cardholder.
dispute_meta.type_of_merchandise_or_servicestring[Required for CHARGE_BACK] The type of merchandise or service (e.g. GROCERY).
dispute_meta.merchant_contactedboolean[Required for CHARGE_BACK] If merchant was contacted.
dispute_meta.contact_dateinteger[Required for CANCEL_RECURRING_PMT and CHARGE_BACK] Contact date (milliseconds since Unix epoch time).
dispute_meta.contact_methodstring[Required for CANCEL_RECURRING_PMT and CHARGE_BACK] Contact method (e.g. PHONE).
dispute_meta.trans_on_same_cardboolean[Required for CHARGED_TWICE|CREDIT_NOT_PROCESSED|DUPLICATE and CHARGED_TWICE|CREDIT_NOT_PROCESSED|PAID_BY_OTHER_MEANS] Are both transactions on the same card? (Proof of other transaction required in dispute_attachments).
dispute_meta.merch_given_attempt_to_resolveboolean[Required for CHARGED_TWICE|CREDIT_NOT_PROCESSED|DUPLICATE and CHARGED_TWICE|CREDIT_NOT_PROCESSED|PAID_BY_OTHER_MEANS] Was the merchant given the chance to resolve?
dispute_meta.contact_namestring[Required for CANCEL_RECURRING_PMT ] Name of contact.
dispute_meta.contact_responsestring[Required forCANCEL_RECURRING_PMT ] Response from contact.
dispute_attachmentsarray of objects[Required for CHARGED_TWICE|CREDIT_NOT_PROCESSED|DUPLICATE and CHARGED_TWICE|CREDIT_NOT_PROCESSED|PAID_BY_OTHER_MEANS] Additional attachments with the dispute form when disputing a card transaction.

Reg E Dispute Reasons (Native Cards)

Value ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌ ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌  ‌‌Description
CANCEL_RECURRING_PMTCanceling recurring payment (i.e. a recurring payment was debited after cancellation).
CHARGE_BACK*Request to credit funds to user.

* Please note that CHARGE_BACK was a general-purpose reason that has been kept for backwards compatibility for certain Platforms but that should not be used for new disputes.
CHARGED_TWICECard was charged twice for the same transaction and the relevant funds were pulled for both transactions.
CHARGED_TWICE|CREDIT_NOT_PROCESSED|DUPLICATEThere 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).
CHARGED_TWICE|CREDIT_NOT_PROCESSED|PAID_BY_OTHER_MEANSThere 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).
INCORRECT_AMOUNTCard charged the incorrect amount
INCORRECT_AMOUNT|ATMUser attempted to withdraw money from ATM and received incorrect amount
UNAUTHORIZED|CARD_IN_HAND*Unauthorized transaction made while user has card in their possession

* Please note that UNAUTHORIZED|CARD_IN_HAND is a reason that has been kept for backwards compatibility for certain Platforms but that the more descriptive UNAUTHORIZED|CARD_IN_HAND|SHARED or UNAUTHORIZED|CARD_IN_HAND|NOT_SHARED should be used for new disputes.
UNAUTHORIZED|CARD_IN_HAND|SHAREDUnauthorized transaction made while user has card in their possession and card is shared with other users.
UNAUTHORIZED|CARD_IN_HAND|NOT_SHAREDUnauthorized transaction made while user has card in their possession and card is not shared with other users.
UNAUTHORIZED|CARD_LOSTUnauthorized transaction made and user has reported a lost or stolen card

Merchant Dispute Request Body

📘

Note on Timestamps Provided for date Properties

Synapse requires submission of timestamps in milliseconds. If a time is supplied to you via a datetime picker (e.g. as a MM-DD-YYYY date at hh:mm:ss time), be sure to account for factors like locale and daylight savings time to convert to UTC day and time and then to milliseconds since Unix epoch time before submitting to Synapse. Please note to send the timestamp for the start of the UTC date corresponding to the option selected by the end-user

KeyTypeDescription
dispute_reasonstring[Required for all disputes] Reason you are disputing the transaction. See the list of dispute reasons below for more information
certification_dateinteger[Required for all merchant disputes] Certification that information provided is true and correct (milliseconds since Unix epoch time). If submitted via Dashboard, this will supplied via a prompt with a checkbox.
dispute_meta.contact_dateinteger[Required for all merchant disputes] Date merchant was contacted. Must be after the transaction was created, and before the certification_date.
dispute_meta.contact_namestring[Required for all merchant disputes] Name of contact at merchant.
dispute_meta.contact_methodstring[Required for all merchant disputes] Contact method for communication with merchant.
dispute_meta.contact_responsestring[Required for all merchant disputes] Response from merchant contact.
dispute_meta.issuestring[Required for MERCHANT|DEFECT_OR_NOT_AS_DESC] Description of the issue (i.e. what was defective or not as described).
dispute_meta.date_receivedinteger[Required for MERCHANT|DEFECT_OR_NOT_AS_DESC] Date of that product was received or service performed. Must be after the transaction was created, and before certification_date.
dispute_meta.matched_verbal_or_written_descboolean[Required for MERCHANT|DEFECT_OR_NOT_AS_DESC] Whether item or service matched verbal or written description.
dispute_meta.matched_receipt_descboolean[Required for MERCHANT|DEFECT_OR_NOT_AS_DESC] If merchandise matched what was described on receipt.
dispute_meta.merchandise_received_as_part_of_transactionboolean[Required for MERCHANT|DEFECT_OR_NOT_AS_DESC] If merchandise was received as part of the transaction.
dispute_meta.merch_refused_return_authboolean[Required if merchandise_received_as_part_of_transaction: "true" for MERCHANT|DEFECT_OR_NOT_AS_DESC] If the merchant refused to provide a return authorization.
dispute_meta.cardhold_told_not_to_returnboolean[Required if merchandise_received_as_part_of_transaction: "true" for MERCHANT|DEFECT_OR_NOT_AS_DESC] The merchant instructed the cardholder not to return item (i.e. to keep it).
dispute_meta.return_dateinteger[Required if merchandise_received_as_part_of_transaction: "true" for MERCHANT|DEFECT_OR_NOT_AS_DESC] Date of product return. Must be after the transaction was created, and before certification_date. Cannot be before date_received (date_received and return_date can be the same calendar day if product was returned the day it was received).
dispute_meta.return_contact_namestring[Required if merchandise_received_as_part_of_transaction: "true" for MERCHANT|DEFECT_OR_NOT_AS_DESC] Contact name of person to whom product was returned.
dispute_meta.return_methodstring[Required if merchandise_received_as_part_of_transaction: "true" for MERCHANT|DEFECT_OR_NOT_AS_DESC] Method by which the product was returned.
dispute_meta.return_responsestring[Required if merchandise_received_as_part_of_transaction: "true" for MERCHANT|DEFECT_OR_NOT_AS_DESC] Response received from merchant on return.
dispute_meta.return_shipping_carrierstring[Optional if merchandise_received_as_part_of_transaction: "true" for MERCHANT|DEFECT_OR_NOT_AS_DESC] Carrier used by the customer to ship the product back to merchant.
dispute_meta.return_tracking_numstring[Optional if merchandise_received_as_part_of_transaction: "true" for MERCHANT|DEFECT_OR_NOT_AS_DESC] Tracking number used for return.
dispute_meta.return_instructions_from_merchstring[Required if merchandise_received_as_part_of_transaction: "true" for MERCHANT|DEFECT_OR_NOT_AS_DESC] Return instructions from the merchant.
dispute_meta.return_refused_by_merchboolean[Required if merchandise_received_as_part_of_transaction: "true" for MERCHANT|DEFECT_OR_NOT_AS_DESC] If merchant refused to accept the return.
dispute_meta.order_canceledboolean[Required for MERCHANT|NOT_RECEIVED] If the order was canceled. Refer to Payload Examples of Merchant Disputes
dispute_meta.order_canceled_dateinteger[Required if order_cancelled: "true" for MERCHANT|NOT_RECEIVED]

When the order was canceled. Must be after the transaction was created, and before certification_date.
dispute_meta.expected_arrival_dateinteger[Optional for MERCHANT|NOT_RECEIVED] When item was originally expected to arrive (milliseconds since Unix epoch time). Must be after the transaction was created, and before certification_date. Must not be after the contact date (expected_arrival_date and contact_date can be on the same calendar day if merchant was contacted the same day that the product was expected to arrive)
dispute_meta.was_item_deliveredboolean[Optional for MERCHANT|NOT_RECEIVED] If the item was delivered.
dispute_meta.prepaid_itemboolean[Optional for MERCHANT|NOT_RECEIVED] If the cardholder prepaid for the item.
dispute_meta.recurring_paymentboolean[Required for MERCHANT|RETURNED_MERCH] If this is a recurring payment.
dispute_meta.recurring_payment_contact_dateinteger[Required if recurring_payment: "true" for MERCHANT|RETURNED_MERCH**] Contact date for cancelling recurring payment. Must be after the node's creation date, and before the certification_date
dispute_meta.recurring_payment_cancellation_dateinteger[Required if recurring_payment: "true" for MERCHANT|RETURNED_MERCH**] Date that recurring payment was cancelled. Must be after the node's creation date, and before the certification_date
dispute_meta.merch_item_descstring[Required for MERCHANT|RETURNED_MERCH] Description of the returned item.
dispute_meta.merch_returnedboolean[Required for MERCHANT|RETURNED_MERCH] Whether merchandise was actually returned or not.
dispute_meta.merch_returned_attemptedboolean[Required if merch_returned: "false" for MERCHANT|RETURNED_MERCH**] If merchandise return was attempted.
dispute_meta.merch_given_chance_to_resolveboolean[Required for MERCHANT|RETURNED_MERCH]
If the merchant was given an attempt to resolve the issue.
dispute_meta.order_canceledboolean[Required for MERCHANT|RETURNED_MERCH] If the order was canceled.
dispute_meta.order_canceled_dateinteger[Required if order_canceled: "true" for MERCHANT|RETURNED_MERCH**] When the order was canceled. Must be after the transaction was created, and before certification_date
dispute_meta.reasonstring[Required for MERCHANT|RETURNED_MERCH] Reason for return or cancellation.
dispute_meta.cancel_policy_providedboolean[Required for MERCHANT|RETURNED_MERCH] If cancellation policy was provided.

Merchant Dispute Reasons

ValueDescription
MERCHANT|DEFECT_OR_NOT_AS_DESCMerchandise/service not as described or defective merchandise/service.
MERCHANT|NOT_RECEIVEDDid not receive merchandise or services (not a quality issue).
MERCHANT|QUALITYIssue with quality of services or merchandise.
MERCHANT|DAMAGED_MERCHDamaged merchandise.
MERCHANT|RETURNED_MERCHReturned merchandise.

Examples of Merchant Disputes

{
    "dispute_reason":"MERCHANT|DEFECT_OR_NOT_AS_DESC",
    "dispute_meta": {
        "contact_date": 1579048986000,
        "contact_name": "Jon Doe",
        "contact_method": "PHONE",
        "contact_response": "Indicated that I could return the merchandise",
        "issue": "product was not in good working order",
        "date_received": 1578962586000,
        "matched_verbal_or_written_desc": true,
        "matched_receipt_desc": false,
        "merchandise_received_as_part_of_transaction": true,
        "return_date": 1579135386000,
        "return_contact_name": "Jon Doe",
        "return_method": "MAIL",
        "return_response": "Thank you for your interest in our product - we're sorry it didn't work out and hope you will consider shopping with us in the future",
        "return_shipping_carrier": "FedEx",
        "return_tracking_num": "3krn3k4n3kn3k",
        "return_instructions_from_merch": "return the merchandise",
        "merch_refused_return_auth": false,
        "return_refused_by_merch": false,
        "cardhold_told_not_to_return": true
    },
    "certification_date": 1579308186000
}

{
    "dispute_reason":"MERCHANT|NOT_RECEIVED",
    "dispute_meta": {
        "contact_date": 1579135386000,
        "contact_name": "Jane Doe",
        "contact_method": "INTERNET",
        "contact_response": "Apologized for the delayed arrival and had received the cancellation",
        "was_item_delivered": true,
        "expected_arrival_date": 1578962586000,
        "prepaid_item": false,    
        "order_canceled": true,
        "order_canceled_date": 1579048986000
    },
    "certification_date": 1579308186000
}

{
    "dispute_reason":"MERCHANT|QUALITY",
    "dispute_meta": {
        "contact_date": 1579135386000,
        "contact_name": "Jane Doe",
        "contact_method": "PHONE",
        "contact_response": "Merchant would not take merchandise back that had quality issue"
    },
    "certification_date": 1579308186000
}

{
    "dispute_reason":"MERCHANT|DAMAGED_MERCH",
    "dispute_meta": {
        "contact_date": 1579135386000,
        "contact_name": "Jane Doe",
        "contact_method": "PHONE",
        "contact_response": "Merchant would not take damaged merchandise back"
    },
    "certification_date": 1579308186000,
    "dispute_attachments": [
        "data:image/gif;base64,SUQs=="
    ]
}

{
    "dispute_reason":"MERCHANT|RETURNED_MERCH",
    "dispute_meta": {
        "contact_date": 1579048986000,
        "contact_name": "John Doe",
        "contact_method": "PHONE",
        "contact_response": "John indicated that the company would be fine with a return",
        "recurring_payment": true,
        "recurring_payment_contact_date": 1578876186000,
        "recurring_payment_cancellation_date": 1578962586000,
        "merch_item_desc": "Blue Jeans",
        "merch_given_chance_to_resolve": false,
        "merch_returned": false,
        "merch_returned_attempted": true,
        "order_canceled": true,
        "order_canceled_date": 1579135386000,
        "reason": "Item did not fit",
        "cancel_policy_provided": false
    },
    "certification_date": 1579308186000
}
Language