Chargebacks

Chargebacks

DOCS

Last updated: Sept 24th, 4:22pm

A chargeback is a consumer protection mechanism that enables a card holder to dispute some charges on his or her credit card.

Activity flow

The flow of activity for a chargeback is:

Step Stakeholder Action
1. Card holder Reports a dispute to a card issuer with information that supports the claim.
2. Card issuer Creates the chargeback according to card association's regulations.

The chargeback moves to the seller's acquirer bank.
3. Acquirer either directly or through a processor Forwards the chargeback to the seller or the financial institution that processed the disputed card transaction for the seller.
4. The seller or the related financial institution
  1. Reviews the chargeback.
  2. Investigates the disputed transaction.
  3. Makes a decision to contest or accept the chargeback.
5. The seller or the related financial institution If a contest decision is made, all evidence information collected during the investigation phase must be submitted to the processor along with the rebuttal response.

You can submit the evidence manually on a processor's web portal or by using a processor-supported batch process. For more information, see Disputes, claims, chargebacks, and bank reversals.

The operations for this API are interfaces into a platform for collection and bulk submission of responses to chargeback events.

For details, see the Chargebacks API Reference.

Integration steps
1. Required Set up your development environment.
2. Required Create chargeback.
3. Required Submit evidence document.

Set up your development environment

Before you can integrate Chargebacks, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.

Then, return to this page to integrate Chargebacks.

Create chargeback

A chargeback enables system tenants to submit information for a chargeback event with supporting evidence to use to respond to the event.

Credit card processors and banks submit these events in chargeback files to clients. Each tuple in the file corresponds to a single chargeback event with information about customer-submitted inquiries and disputes to the processors and banks against customer credit card and bank transactions. 

    1curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer-support/chargeback-events \
    2  -H "Content-Type: application/json" \
    3  -H "Authorization: Bearer <Access-Token>" \
    4  -d '{
    5  "raw_event_info": "<?xmlversion="
    6  1.0 "encoding="
    7  UTF - 8 "?><document><batch_chargeback_advice><header><file_function>CHB</file_function><format_version>1.0</format_version><file_id>121610</file_id><creation_time>2017-11-15T07:15:27Z</creation_time><initiating_party><id>PYPL</id></initiating_party><recipient_party><id>BRTE</id></recipient_party></header><dataset><chargeback_advice><environment><card_scheme>VISA</card_scheme><acquirer><id>WLFG</id></acquirer><acquiring_processor><id>FDMS</id></acquiring_processor><authorization_processor><id>FDMS</id></authorization_processor><payment_acceptor/><acquirer_assigned_mid/><scheme_assigned_mid><id>174030076999</id></scheme_assigned_mid></environment><chargeback_event><notice_type>FTCB</notice_type><raw_notice_type>2</raw_notice_type><dispute_date>2017-11-10T08:00:00Z</dispute_date><dispute_amount><currency>USD</currency><amount>12.50</amount></dispute_amount><dispute_funding_amount><amount>0</amount></dispute_funding_amount><financial_impact_type>DEBT</financial_impact_type><raw_reason_code>UA</raw_reason_code><amex_specific_details/></chargeback_event><transaction><transaction_id><transaction_time>2017-11-10T20:42:40Z</transaction_time><transaction_reference>NxLlhqkymOpBAdbeF</transaction_reference></transaction_id><transaction_type>CRDP</transaction_type><transaction_amount><currency>USD</currency></transaction_amount><charge_description>PP*freshairtesting</charge_description><transaction_references><retrieval_reference>270256011701</retrieval_reference><intermediary_agent_reference>286160</intermediary_agent_reference></transaction_references><auth_detail><auth_amount><currency>USD</currency><amount>12.50</amount></auth_amount><auth_code>010203</auth_code></auth_detail></transaction></chargeback_advice><chargeback_advice><environment><card_scheme>VISA</card_scheme><acquirer><id>WLFG</id></acquirer><acquiring_processor><id>FDMS</id></acquiring_processor><authorization_processor><id>FDMS</id></authorization_processor><payment_acceptor/><acquirer_assigned_mid/><scheme_assigned_mid><id>174030076999</id></scheme_assigned_mid></environment><chargeback_event><notice_type>FTCB</notice_type><raw_notice_type>2</raw_notice_type><dispute_date>2017-11-10T08:00:00Z</dispute_date><dispute_amount><currency>USD</currency><amount>11.50</amount></dispute_amount><dispute_funding_amount><amount>0</amount></dispute_funding_amount><financial_impact_type>DEBT</financial_impact_type><raw_reason_code>UA</raw_reason_code><amex_specific_details/></chargeback_event><transaction><transaction_id><transaction_time>2017-11-10T20:42:32Z</transaction_time><transaction_reference>ukvAQdRKVBf5J0AUh</transaction_reference></transaction_id><transaction_type>CRDP</transaction_type><transaction_amount><currency>USD</currency></transaction_amount><charge_description>PP*freshairtesting</charge_description><transaction_references><retrieval_reference>270256011701</retrieval_reference><intermediary_agent_reference>286158</intermediary_agent_reference></transaction_references><auth_detail><auth_amount><currency>USD</currency><amount>11.50</amount></auth_amount><auth_code>010203</auth_code></auth_detail></transaction></chargeback_advice><chargeback_advice><environment><card_scheme>VISA</card_scheme><acquirer><id>WLFG</id></acquirer><acquiring_processor><id>FDMS</id></acquiring_processor><authorization_processor><id>FDMS</id></authorization_processor><payment_acceptor/><acquirer_assigned_mid/><scheme_assigned_mid><id>174030076999</id></scheme_assigned_mid></environment><chargeback_event><notice_type>TKRL</notice_type><raw_notice_type>1</raw_notice_type><dispute_date>2017-11-10T08:00:00Z</dispute_date><dispute_amount><currency>USD</currency><amount>10.50</amount></dispute_amount><dispute_funding_amount><amount>0</amount></dispute_funding_amount><financial_impact_type>F</financial_impact_type><raw_reason_code>UA</raw_reason_code><amex_specific_details/></chargeback_event><transaction><transaction_id><transaction_time>2017-11-10T20:42:08Z</transaction_time><transaction_reference>oXjLpUdozKFDMmo70</transaction_reference></transaction_id><transaction_type>CRDP</transaction_type><transaction_amount><currency>USD</currency></transaction_amount><charge_description>PP*freshairtesting</charge_description><transaction_references><retrieval_reference>270256011701</retrieval_reference><intermediary_agent_reference>286145</intermediary_agent_reference></transaction_references><auth_detail><auth_amount><currency>USD</currency><amount>10.50</amount></auth_amount><auth_code>010203</auth_code></auth_detail></transaction></chargeback_advice></dataset><trailer><file_response><response_code>APPR</response_code><reason_code>APPR</reason_code><message>SUCCESS</message></file_response><file_totals><type>DBT</type><count>3</count></file_totals></trailer></batch_chargeback_advice></document>",
    8  "raw_event_info_format": "XML",
    9  "processor": "BNP",
    10  "acquirer": "HDFC",
    11  "processing_intent": "PROCESSOR_RESPONSE",
    12  "disputed_transaction": {
    13    "payment_attempt_id": "24R974",
    14    "sender": {
    15      "sender_id": "3525684636",
    16      "sender_name": {
    17        "prefix": "Mr",
    18        "given_name": "Danielle",
    19        "surname": "McCoy",
    20        "middle_name": "T",
    21        "suffix": "T",
    22        "alternate_full_name": "McCoy"
    23      },
    24      "sender_billing_address": {
    25        "line1": "!827 Kings Street",
    26        "line2": "Central square",
    27        "city": " Oklahoma",
    28        "state": "OK",
    29        "country_code": "US",
    30        "postal_code": "3628"
    31      },
    32      "sender_email": "[email protected]",
    33      "sender_phone": {
    34        "country_code": "234",
    35        "national_number": "98988998883",
    36        "extension_number": "948899"
    37      }
    38    },
    39    "receiver": {
    40      "receiver_id": "3525684636",
    41      "receiver_name": {
    42        "prefix": "Mr",
    43        "given_name": "Richard",
    44        "surname": "Danielle",
    45        "middle_name": "T",
    46        "suffix": "T",
    47        "alternate_full_name": "Richard"
    48      },
    49      "receiver_email": "[email protected]",
    50      "receiver_phone": {
    51        "country_code": "234",
    52        "national_number": "98988998883",
    53        "extension_number": "948899"
    54      }
    55    },
    56    "trans_id": "232554535",
    57    "trans_description": "Test",
    58    "trans_amount": {
    59      "currency_code": "USD",
    60      "value": "50"
    61    },
    62    "trans_time": "2001-01-13T12:19:00Z",
    63    "trans_status": "COMPLETED",
    64    "trans_session_info": {
    65      "device_fingerprint": "356612364",
    66      "ip": "134.335.345.34",
    67      "visitor_id": "Test124",
    68      "flash_shared_object": "test"
    69    },
    70    "card_trans_info": {
    71      "card_last_four": "5234",
    72      "card_type": "BANK_NOT_CREDIT_CARD",
    73      "card_billing_name": {
    74        "prefix": "Mr",
    75        "given_name": "Danielle",
    76        "surname": "McCoy",
    77        "middle_name": "T",
    78        "suffix": "T",
    79        "alternate_full_name": "McCoy"
    80      },
    81      "card_trans_id": "523555",
    82      "card_trans_amount": {
    83        "currency_code": "USD",
    84        "value": "50"
    85      },
    86      "trans_settlement_status": "Completed",
    87      "trans_settlement_time": "2001-01-13T12:19:00Z",
    88      "trans_settlement_days": 6,
    89      "trans_auth_time": "2001-01-13T12:19:00Z",
    90      "trans_auth_status": "SUCCESS",
    91      "authorization_code": "Test",
    92      "three_ds_eci": "ECI_01",
    93      "three_ds_auth_status": "SUCCESS",
    94      "mpi_vendor_three_ds": "test",
    95      "trans_cvv_response": "CVV_MATCHES",
    96      "trans_avs_response": "POSTAL_CODE_MATCHES",
    97      "seller_account_number": "36595020022245"
    98    }
    99  },
    100  "refund_transaction": {
    101    "refund_amount": {
    102      "currency_code": "USD",
    103      "value": "50"
    104    },
    105    "refund_trans_time": "2001-01-13T12:19:00Z",
    106    "refund_trans_id": "12344232"
    107  },
    108  "event_response_type": "ACCEPTANCE",
    109  "evidences": [{
    110    "evidence_type": "PROOF_OF_DG_DOWNLOAD",
    111    "evidence_info": [{
    112      "name": "DOWNLOAD_DATE",
    113      "value": "2017-03-01"
    114    }],
    115    "support_doc_ids": ["234DFG3", "344S34G"]
    116  }]
    117}'

    The response shows the unique reference ID for the chargeback event:

      1{
      2  "unique_reference_id": "AB12DGX"
      3}

      Submit evidence document

      You can submit an evidence document to processors for a chargeback:

        1curl -v -X POST https://api-m.sandbox.paypal.com/v1/customer-support/submit-evidence-docs \
        2  -H "Content-Type:  multipart/related; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" \
        3  -H "Authorization: Bearer <Access-Token>" \
        4  -F 'document_info={
        5        "document_name": "ABC",
        6        "document_type": "pdf"
        7    };type=application/json' \
        8   -F '[email protected]'

        The response shows the unique reference ID of the chargeback event:

          1{
          2  "unqiue_reference_id": "AB12DGX"
          3}

          Additional information

          ReferencePayPal.comPrivacyCookiesSupportLegalContact

          If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more