A chargeback (cbk_*) is a challenge to a card payment you received, reported by the card network. Your response to it is the Chargeback Evidence object. To learn more, see Respond to a chargeback.
The object is everything inside data. The field names below are relative to it: attributes.amount is data.attributes.amount in the response.
Fields
string
required
Chargeback ID (cbk_*).
string
required
Resource type. Always chargeback.
object
required
The chargeback’s details.
Hide attributes
integer
required
Disputed amount in the currency’s smallest unit.
string
required
Uppercase ISO 4217 currency code of the disputed amount.
object | null
required
Natural’s fee for this case, billed once when the case opens. It can be billed before the disputed amount is withheld and isn’t refunded if you win. Null when no fee applies or the fee was voided.
Hide fee
integer
required
Fee amount in cents.
string
required
Currency of the fee. Always USD.
string
required
Response and outcome state. While the case is needsResponse, submitted, or underReview, the disputed amount is withheld from your available balance. The hold can post shortly after the case is created. Won returns the amount. Lost, accepted, and expired do not. One of: needsResponse, expired, accepted, submitted, underReview, won, lost. See Statuses.
string
required
Card network that reported the case. One of: visa, mastercard, discover, unknown.
object
required
Why the payment was charged back, as the card network reported it.
Hide reason
string
required
Natural’s grouping of the network reason code. unknown when Natural has no group for the code. One of: fraud, authorization, processingError, duplicate, notReceived, unacceptableOrCanceled, creditNotProcessed, unknown.
string
required
Network reason code, interpreted with the network.
string | null
required
Readable reason description, or null when unavailable.
string
required
Deadline for accepting or responding to this chargeback. Enforced.
string | null
required
When Natural accepted and froze the response. This does not establish provider acknowledgment.
string
required
When Natural recorded the case.
string
required
When the case last changed.
object
required
Related resources, each by type and ID.
Hide relationships
object
required
The disputed card payment.
Hide cardPayment
object
required
Related resource identifier.
Hide data
string
required
Resource type. Always cardPayment.
string
required
Card payment ID (cpy_*).
object
required
The payment intent the disputed card payment paid.
Hide paymentIntent
object
required
Related resource identifier.
Hide data
string
required
Resource type. Always paymentIntent.
string
required
Payment intent ID (pmi_*).
object
required
The party that received the disputed payment.
Hide customerParty
object
required
Related resource identifier.
Hide data
string
required
Resource type. Always party.
string
required
ID of the party that received the payment (pty_*).
Statuses
Status
Meaning
Can become
needsResponse
Waiting for you to accept the chargeback or submit evidence before responseDueAt.
submitted, accepted, expired, won, lost
expired
responseDueAt passed before you accepted or submitted evidence.
won, lost
accepted
You accepted the chargeback instead of contesting it.
won, lost
submitted
You submitted evidence and Natural froze it. The provider hasn’t acknowledged it yet.
underReview, won, lost
underReview
The provider acknowledged your evidence. The outcome is pending.
won, lost
won
The provider reported a win.
lost
lost
The provider reported a loss, or a second chargeback.
Final
Events
chargeback.created: A chargeback case was opened against a card payment. The fee is billed when the case opens, so it’s already on chargeback.created.
chargeback.updated: A chargeback case moved: accepted, representment submitted, acknowledged, or the response window expired.