Chargebacks

Chargebacks occur when a cardholder disputes a transaction with their bank. The bank reverses the payment and notifies TapTree. You can use the Chargebacks API to monitor, respond to, and manage chargebacks across your payments. Chargebacks are also visible as records within the Settlements API.

Discover the Chargebacks resource using Postman:

TapTree Postman Collection

Chargebacks are only available in live mode. Test tokens will receive a 404 response, since chargebacks only occur on real transactions.

Chargeback lifecycle

A chargeback goes through a series of statuses from the moment it is received until it is resolved. Understanding the lifecycle helps you respond quickly and effectively.

Statuses

StatusDescriptionTerminal?
openChargeback received. Funds are withheld. You must respond before deadline_at.No
acceptedYou accepted the chargeback. Funds are returned to the cardholder.Yes
disputedYou submitted evidence (representment). Awaiting card network decision.No
wonThe card network ruled in your favor. Funds are returned to you.Yes
lostThe card network ruled against you. Funds are returned to the cardholder.Yes

Status flow

disputeacceptwonlostopendisputedacceptedwonlost

Key facts

Chargebacks require immediate attention. When you receive a chargeback webhook (transactions.chargeback.open), you must respond before the deadline_at timestamp. If no action is taken before the deadline, the chargeback is automatically accepted.

  • Each chargeback includes a deadline_at field — this is your hard cutoff. Deadlines are short, so act as soon as you receive the webhook.
  • Chargebacks incur processing fees regardless of whether you win or lose the dispute.
  • If a dispute escalates to arbitration, the losing party pays the card network’s ruling fee — as of 2025, Visa charges $600 per ruling and Mastercard fees can exceed $500.
  • Chargeback events are delivered to the webhook_url of the parent payment. See Webhooks for details.

Dispute process

When you dispute a chargeback, the process goes through up to three stages before a final decision is reached. TapTree reports the outcome as won or lost — the stages below happen between the card network and the issuing bank.

  1. Representment — You submit evidence to challenge the chargeback. The issuing bank reviews it and either accepts your evidence or upholds the chargeback.
  2. Pre-arbitration — If the issuer rejects your evidence, there is a second round where either party can accept liability or push the case further.
  3. Arbitration — Neither side concedes, so the card network (Visa or Mastercard) steps in as the final judge and makes a binding ruling. The losing party pays the network’s arbitration fee.

3D Secure and liability shift

3D Secure 2 verifies the cardholder’s identity before authorization. It supports risk-based frictionless authentication, so low-risk transactions can be approved without a challenge step — reducing fraud exposure with minimal checkout friction.

When a cardholder successfully authenticates with 3D Secure, fraud-related chargeback liability shifts from your business to the cardholder’s issuing bank. This applies to fraud reason codes only — for example Visa 10.1–10.5 and Mastercard 4837/4840/4849/4871.

3D Secure does not protect against non-fraud disputes such as "product not received", "not as described", or "credit not processed". Liability shift also does not apply when authentication fails, when enrollment status cannot be confirmed, for data-only 3DS flows, or for certain merchant-initiated and recurring transactions.

Endpoints

Retrieve a chargeback

GET/v1/chargebacks/:id

Fetch details of a specific chargeback using its unique identifier.

List all chargebacks

GET/v1/chargebacks

Retrieve a paginated list of all chargebacks.

List payment chargebacks

GET/v1/payments/:id/chargebacks

Retrieve all chargebacks for a specific payment.

The chargeback model

The chargeback model contains all the details related to a disputed transaction, including the reason, amount, deadline, acquirer information, and dispute status.

Core attributes

  • Name
    id
    Type
    string
    Description

    Unique identifier for the chargeback, prefixed with cb_.

  • Name
    object
    Type
    string
    Description

    The object type. Always chargeback.

  • Name
    payment_id
    Type
    string
    Description

    The ID of the original payment that was charged back, prefixed with pay_.

  • Name
    status
    Type
    string
    Description

    Status of the chargeback.

    Possible values: open accepted disputed won lost

  • Name
    reason
    Type
    object
    Description

    The chargeback reason from the card network.

  • Name
    amount
    Type
    object
    Description

    The chargeback amount.

  • Name
    deadline_at
    Type
    datetime
    Description

    The deadline to respond to the chargeback, in ISO 8601 format. After this deadline, the chargeback is automatically accepted.

  • Name
    acquirer
    Type
    object
    Description

    Information about the acquirer handling the chargeback.

  • Name
    dispute
    Type
    object
    Description

    Dispute information, if the chargeback has been disputed.

  • Name
    consumer_account_number
    Type
    string
    Description

    Masked card number of the consumer who initiated the chargeback.

  • Name
    created_at
    Type
    datetime
    Description

    Timestamp of when the chargeback was created, in ISO 8601 format.

  • Name
    updated_at
    Type
    datetime
    Description

    Timestamp of the last update.

  • Name
    links
    Type
    object
    Description

    Links related to the chargeback object.

Response object

{
 "object": "chargeback",
 "id": "cb_8ZkT3mN9pRw",
 "payment_id": "pay_AzoSgo2h7mB",
 "status": "open",
 "reason": {
   "code": "10.1",
   "description": "EMV Liability Shift Counterfeit Fraud"
 },
 "amount": {
   "value": "25.50",
   "currency": "EUR"
 },
 "deadline_at": "2026-03-15T23:59:59.000Z",
 "acquirer": {
   "name": "TapTree Acquiring",
   "reference": "ACQ-REF-7K9MX2P3",
   "case_id": "CASE-A8N4R7"
 },
 "consumer_account_number": "5**************1",
 "created_at": "2026-03-01T10:30:00.000Z",
 "updated_at": "2026-03-01T10:30:00.000Z",
 "links": {
   "api": {
     "href": "https://api.taptree.org/v1/chargebacks/cb_8ZkT3mN9pRw",
     "type": "application/json"
   },
   "payment": {
     "href": "https://api.taptree.org/v1/payments/pay_AzoSgo2h7mB",
     "type": "application/json"
   }
 }
}
GET/v1/chargebacks/:id

Retrieve a Chargeback

Fetch details of a specific chargeback using its unique identifier. The response includes the full chargeback details, reason, acquirer info, and dispute status.

Required parameters

  • Name
    id
    Type
    string
    Description

    The unique identifier of the chargeback to retrieve. In the endpoint URL, substitute id with the specific chargeback's ID, such as cb_8ZkT3mN9pRw.

Request

GET
/v1/chargebacks/cb_8ZkT3mN9pRw
curl https://api.taptree.org/v1/chargebacks/cb_8ZkT3mN9pRw \
  -H "Authorization: Bearer {token}"

Example response

{
  "object": "chargeback",
  "id": "cb_8ZkT3mN9pRw",
  "payment_id": "pay_AzoSgo2h7mB",
  "status": "open",
  "reason": {
    "code": "10.1",
    "description": "EMV Liability Shift Counterfeit Fraud"
  },
  "amount": {
    "value": "25.50",
    "currency": "EUR"
  },
  "deadline_at": "2026-03-15T23:59:59.000Z",
  "acquirer": {
    "name": "TapTree Acquiring",
    "reference": "ACQ-REF-7K9MX2P3",
    "case_id": "CASE-A8N4R7"
  },
  "consumer_account_number": "5**************1",
  "created_at": "2026-03-01T10:30:00.000Z",
  "updated_at": "2026-03-01T10:30:00.000Z",
  "links": {
    "api": {
      "href": "https://api.taptree.org/v1/chargebacks/cb_8ZkT3mN9pRw",
      "type": "application/json"
    },
    "payment": {
      "href": "https://api.taptree.org/v1/payments/pay_AzoSgo2h7mB",
      "type": "application/json"
    }
  }
}
GET/v1/chargebacks

List all chargebacks

Retrieve a paginated list of all chargebacks for your acceptor. Chargebacks are ordered by creation date, newest first. Use limit, starting_after, and ending_before parameters for pagination.

Optional query parameters

  • Name
    limit
    Type
    integer
    |
    Optional
    optional
    |
    Default
    default=10
    Description

    Specify the maximum number of chargebacks to return in one response, up to 100.

  • Name
    starting_after
    Type
    string
    |
    Optional
    optional
    Description

    A chargeback id for cursor-based pagination. Returns chargebacks listed after the specified ID.

    Example: If the last chargeback id you accessed was cb_8ZkT3mN9pRw, use starting_after=cb_8ZkT3mN9pRw to view chargebacks following it.

  • Name
    ending_before
    Type
    string
    |
    Optional
    optional
    Description

    A chargeback id for cursor-based pagination. Returns chargebacks listed before the specified ID.

    To view chargebacks preceding cb_8ZkT3mN9pRw, include ending_before=cb_8ZkT3mN9pRw in your request.

Request

GET
/v1/chargebacks
curl -G https://api.taptree.org/v1/chargebacks \
  -H "Authorization: Bearer {token}" \
  -d limit=20

Example response

{
  "has_more": false,
  "data": [
    {
      "object": "chargeback",
      "id": "cb_8ZkT3mN9pRw",
      "payment_id": "pay_AzoSgo2h7mB",
      "status": "open",
      "reason": {
        "code": "10.1",
        "description": "EMV Liability Shift Counterfeit Fraud"
      },
      "amount": {
        "value": "25.50",
        "currency": "EUR"
      },
      "deadline_at": "2026-03-15T23:59:59.000Z",
      "created_at": "2026-03-01T10:30:00.000Z",
      "links": {
        "api": {
          "href": "https://api.taptree.org/v1/chargebacks/cb_8ZkT3mN9pRw",
          "type": "application/json"
        }
      }
    }
  ]
}
GET/v1/payments/:id/chargebacks

List payment chargebacks

Retrieve all chargebacks for a specific payment. Use this to check if a particular payment has been charged back.

Required parameters

  • Name
    id
    Type
    string
    Description

    The payment ID (e.g. pay_AzoSgo2h7mB).

Request

GET
/v1/payments/pay_AzoSgo2h7mB/chargebacks
curl https://api.taptree.org/v1/payments/pay_AzoSgo2h7mB/chargebacks \
  -H "Authorization: Bearer {token}"

Example response

{
  "has_more": false,
  "data": [
    {
      "object": "chargeback",
      "id": "cb_8ZkT3mN9pRw",
      "payment_id": "pay_AzoSgo2h7mB",
      "status": "open",
      "reason": {
        "code": "10.1",
        "description": "EMV Liability Shift Counterfeit Fraud"
      },
      "amount": {
        "value": "25.50",
        "currency": "EUR"
      },
      "deadline_at": "2026-03-15T23:59:59.000Z",
      "created_at": "2026-03-01T10:30:00.000Z",
      "links": {
        "api": {
          "href": "https://api.taptree.org/v1/chargebacks/cb_8ZkT3mN9pRw",
          "type": "application/json"
        }
      }
    }
  ]
}

Was this page helpful?