Disputes

A dispute (also known as a chargeback), is a request initiated by a cardholder through their issuing bank to reverse a previously completed transaction. Disputes are typically raised when a customer believes a charge was unauthorized, fraudulent, or when the purchased product or service was not received as expected.

When a dispute is opened, the merchant receives a webhook notification with all relevant details. From that moment, the merchant has 7 calendar days to respond by submitting the required supporting documentation to appeal the chargeback.

Once a chargeback is initiated, the disputed amount is temporarily withheld from the merchant’s Localpayment account balance to ensure fund availability during the review process. This reservation prevents the merchant from accessing or using the funds while the dispute is being evaluated. If the dispute is resolved in the merchant’s favor, the reserved funds are fully restored to their account. However, if the cardholder’s claim is upheld, the reserved amount is permanently debited and returned to the issuing bank, making the funds available again to the customer.

Dispute Process

The following steps outline how the dispute process works from initiation to resolution:

1. Customer Dispute: The customer initiates a dispute with their card-issuing bank.
2. Issuer Request: The card-issuing bank requests a dispute for the transaction.
3. Acquirer Notification: The acquiring bank requests a dispute from Localpayment.
4. Merchant Notification: Localpayment sends a notification to the merchant with the dispute details.
5. Merchant Response: The merchant receives, processes, and sends the required supporting documentation to Localpayment within the specified timeframe. (7 days)
6. Documentation to Acquirer: Localpayment forwards the documentation to the acquiring bank for review.
7. Documentation to Issuer: The acquiring bank forwards the documentation to the card-issuing bank for review.
8. Issuer Decision: The card-issuing bank evaluates the provided evidence and makes a final decision on the dispute.
9. Result to Acquirer: The card-issuing bank sends the result to the acquiring bank.
10. Result to Localpayment: The acquiring bank communicates the result to Localpayment.
11. Merchant Notification: Localpayment sends a notification to the merchant with the updated dispute status.

New Dispute Notification

When a new dispute occurs, Localpayment will send a webhook to the configured endpoint with status Received.

Sample webhook for a new dispute

{
  "transactionType": "ChargeBack",
  "data": {
    "externalId": "7fd9c89a-4f6e-4912-b478-890b86429df1",
    "internalId": "3b95aeb9-c22e-4301-909e-d160e1dcebe2",
    "accountNumber": "032.032.00000001",
    "transactionType": "ChargeBack",
    "comment": "ChargeBack transaction originated by: 7fd9c89a-4f6e-4912-b478-890b86429df1",
    "status": {
      "code": "100",
      "description": "Received",
      "detail": "Chargeback has been received"
    },
    "dateCreated": "2025-01-22T20:18:50Z",
    "dateProcessed": "2025-01-22T20:20:09Z"
  }
}

Merchants have 7 calendar days from the moment of notification to submit valid documentation to contest the dispute. If no documentation is submitted within this period, the dispute is closed in favor of the cardholder.

Responding to a Dispute

When you receive a webhook indicating a new dispute (Received), you can either:

• Respond with supporting documentation to contest the chargeback.
• Accept the dispute by taking no further action, which will result in the chargeback being finalized in favor of the customer.

To contest a dispute, you need to submit documentation that supports the validity of the transaction to Localpayment. You must compile all supporting evidence into a single PDF file. The following is a suggested list of evidence to include, depending on the type of product or service:

• Physical Product
  • Shipping confirmation with matching billing address
  • Delivery tracking numbers
  • Pickup forms with cardholder signature
  • Photos of ID and delivery
  • Screenshots of order confirmation, signed contracts, or recurring payments
• Digital Products or Services
  • Customer’s IP address and email at the time of purchase
  • Logs proving access or downloads
  • Screenshots or metadata of activity
  • Device info and geolocation data
  • Proof of valid recurring usage
  • Proof of refund (if already issued)
• Offline Services
  • Service agreement or signed contract
  • Confirmation of usage or appointment attendance
  • Identity verification at the time of service
  • Service fulfillment details
  • Proof of related purchases or loyalty benefits

Uploading Dispute Documentation

To submit the supporting file, send a POST request to the Upload Documents to Dispute a Chargeback endpoint.

Request Example

curl --location \
--request POST 'https://api.stage.localpayment.com/api/chargeback/documentation/{externalId}' \
--header 'Authorization: Bearer <your_access_token>' \
--form 'files=@"/path/to/file"'

Successful Response

{
  "externalId": "7fd9c89a-4f6e-4912-b478-890b86429df1",
  "internalId": "3b95aeb9-c22e-4301-909e-d160e1dcebe2",
  "status": {
    "code": "101",
    "description": "DocReceived",
    "detail": "Dispute documentation received"
  }
}

Once the documentation is received, the dispute’s status changes to DocReceived.

Dispute Status

A dispute can go through several statuses depending on the outcome:

• Received: Initial state. Dispute has been received, no documentation yet.
• DocReceived: Documentation submitted by the merchant.
• InDispute: Documentation is being reviewed by the acquirer or issuer.
• DisputeLost: Dispute ruled in favor of the customer. Funds are not returned.
• DisputeWon: Dispute ruled in favor of the merchant. Funds are returned.
• Complete: Dispute closed with no merchant response—defaulted in favor of the customer.

Whenever the status changes, Localpayment will notify your application through a webhook.