Create a Dispute

POSThttps://api.omise.co/charges/:id/disputes

Create a new dispute for a specific charge. This initiates the chargeback process for the associated transaction.

---

Request Parameters

Required - 1 fieldRequired Parameters

▼

`id`STRING(required)

Charge ID to create a dispute for (path parameter). The charge must be in a disputable state. Format: chrg_test_ or chrg_live_ followed by alphanumeric string.

Example:"chrg_test_5xuy4w91xqz7d1w9u0t"

---

Responses

200

Successful creation

Returns the newly created dispute object with initial status set to "open".

Response includes:

• id - Dispute ID (dspt_test_ or dspt_live_ prefix)
• object - "dispute"
• livemode - Whether this is a live mode dispute
• status - Initial status (open)
• amount - Disputed amount in smallest currency unit
• currency - Three-letter ISO currency code
• reason_code - Reason for dispute
• reason_message - Human-readable reason description
• charge - Associated charge ID
• message - Response message (null initially)
• documents - List of evidence documents (empty initially)
• created_at - When dispute was created
• closed_at - When dispute was closed (null for open disputes)

400

Bad request

Request validation failed. Check the error message for details.

Common causes:

• Invalid charge ID format
• Missing required parameters
• Malformed request body

401

Unauthorized

Authentication failed. Invalid or missing API key.

Common causes:

• Missing Authorization header
• Invalid secret key
• Using public key instead of secret key
• Incorrect HTTP Basic Auth format

404

Not found

Charge not found.

Common causes:

• Incorrect charge ID
• Charge belongs to different account
• ID typo or formatting error

422

Unprocessable entity

Dispute cannot be created for this charge.

Common causes:

• Charge already has an existing dispute
• Charge is not in a disputable state
• Charge has been refunded
• Charge is too old to dispute

5xx

Server error

Server-side error occurred. These are rare but should be handled gracefully.

How to handle:

• Retry the request with exponential backoff
• Check status.omise.co for service incidents
• See Error Handling for detailed guidance

---

Code samples

cURL

curl https://api.omise.co/charges/chrg_test_5xuy4w91xqz7d1w9u0t/disputes \
  -X POST \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

Ruby

require 'omise'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

charge = Omise::Charge.retrieve('chrg_test_5xuy4w91xqz7d1w9u0t')
dispute = charge.disputes.create

Python

import omise

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

charge = omise.Charge.retrieve('chrg_test_5xuy4w91xqz7d1w9u0t')
dispute = charge.disputes.create()

Node.js

const omise = require('omise')({
  secretKey: 'skey_test_5xuy4w91xqz7d1w9u0t'
});

const dispute = await omise.charges.createDispute('chrg_test_5xuy4w91xqz7d1w9u0t');

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$charge = OmiseCharge::retrieve('chrg_test_5xuy4w91xqz7d1w9u0t');
$dispute = $charge->disputes()->create();

Java

Client client = new Client.Builder()
    .secretKey("skey_test_5xuy4w91xqz7d1w9u0t")
    .build();

Dispute dispute = client.charges().createDispute("chrg_test_5xuy4w91xqz7d1w9u0t");

C#

var client = new Client("skey_test_5xuy4w91xqz7d1w9u0t");

var dispute = await client.Charges.CreateDispute("chrg_test_5xuy4w91xqz7d1w9u0t");

Go

client, _ := omise.NewClient(
    "pkey_test_5xuy4w91xqz7d1w9u0t",
    "skey_test_5xuy4w91xqz7d1w9u0t",
)

dispute, _ := client.CreateDispute("chrg_test_5xuy4w91xqz7d1w9u0t")

---

Error and result codes

Common Error Codes

Code	Description	Resolution
bad_request	Invalid parameters	Check charge ID format
authentication_failure	Invalid API key	Verify your secret key is correct
not_found	Charge not found	Check charge ID is correct
invalid_charge_id	Charge ID format invalid	Use valid chrg_ format
dispute_already_exists	Charge already has a dispute	Cannot create duplicate disputes
charge_not_disputable	Charge cannot be disputed	Verify charge status and age

Dispute Status Values

Status	Description
open	Newly initiated, awaiting your response
pending	Under review with merchant response submitted
won	Merchant won the dispute
lost	Merchant lost the dispute

Reason Codes

Code	Description
fraudulent	Customer claims unauthorized transaction
unrecognized	Customer doesn't recognize the charge
duplicate	Customer claims duplicate charge
goods_or_services_not_provided	Product/service not received
not_as_described	Product significantly different from description
credit_not_processed	Refund promised but not received
general	Other reasons

---

🔑API Credentials

▼

Try it out

Required - 1 fields

▼

id(Required)

Your IP: ...Loading...