Skip to navigation
API ReferenceOutcomesDisputes

Open a dispute

Opens a dispute on an outcome charge, usually when the end customer complains through your own support channel. A dispute stops a pending charge from confirming. Decide it with resolve before decide_by; if nobody does, default_decision applies. Disputes can be opened until the charge’s reversal horizon passes. A dispute on a confirmed charge holds its lock: if the horizon passes while the dispute is open, the charge stays disputed and doesn’t lock. Deciding uphold then locks it (lock_reason: dispute_upheld), and reverse reverses it.

Authentication

AuthorizationBearer

A secret key (rl_sk_test_..., rl_sk_live_...) or a restricted key with limited scopes (rl_rk_test_..., rl_rk_live_...). A restricted key can carry agent: true and an expires_at, and is what a coding agent should hold. Keys end in a checksum so secret scanners can recognize them. People create, roll and revoke keys in the dashboard; GET /v1/api_keys lists them, masked.

Request

This endpoint expects an object.
outcome_chargestringRequired
reason_codeenumRequired
Why a charge was reversed. New codes may be added.
opened_byenumOptionalDefaults to end_customer

Who raised it. Use end_customer when you’re recording your customer’s complaint.

Allowed values:
descriptionstringOptional<=2000 characters
The complaint, in brief.
evidenceobjectOptional

What shows an outcome happened, stamped on the outcome charge. Keep it short and factual; it is shown to people deciding disputes. Free text is sanitized before it reaches dashboards or agent tools.

metadatamap from strings to stringsOptional
Up to 50 keys of your own, with keys up to 40 characters and values up to 500 characters.

Response

The open dispute.
idstring
object"dispute"
outcome_chargestring
customerstring
statusenum

open until decided. upheld: the charge stands. reversed: the charge was reversed.

Allowed values:
reason_codeenum
Why a charge was reversed. New codes may be added.
opened_byenum
Allowed values:
deciderenum

Who decides. Always merchant (you).

Allowed values:
decide_bydatetime

The deadline. dispute.decision_due fires 24 hours before it.

default_decisionenum
Allowed values:
metadatamap from strings to strings
Up to 50 keys of your own, with keys up to 40 characters and values up to 500 characters.
livemodeboolean
created_atdatetime
rulestringOptional
The rule key, when a rule opened it.
trigger_eventstringOptional
descriptionstringOptional
evidenceobjectOptional

What shows an outcome happened, stamped on the outcome charge. Keep it short and factual; it is shown to people deciding disputes. Free text is sanitized before it reaches dashboards or agent tools.

decisionenumOptional
Allowed values:
decided_byenumOptional

merchant if you decided, default if the deadline passed.

Allowed values:
actorobjectOptional

Who recorded the decision. Left out while open and when decided_by is default.

decision_notestringOptional
decided_atdatetimeOptional
reversalstringOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error