---
title: "Create on-us dispute"
method: POST
path: "/v1/on-us-dispute"
tags: ["On-Us"]
---

# Create on-us dispute

`POST /v1/on-us-dispute`

## Request

- Base URL: `https://sandbox.pismolabs.io/disputes`
- URL: `https://sandbox.pismolabs.io/disputes/v1/on-us-dispute`
- Auth: HTTP bearer

Create an on-us dispute. This allows issuers to create a dispute for a non-branded authorization or transaction performed with a Pismo-issued card. Disputes are initially created with a `PENDING` status. Once ready, the issuer must call [Update on-us dispute](ref:post-update-on-us-dispute) with the `OPEN` event to submit the dispute and move the dispute's status to `OPENED`. 

For more information about on-us disputes and its state machine, refer to the [On-us disputes](https://developers.pismo.io/pismo-docs/docs/on-us-disputes) guide.

This endpoint generates a [On-us dispute created](https://developers.pismo.io/events/docs/disputes-disputes-creation-1) event.

**Notes:** 
  * This endpoint takes an account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a <b>401 Unauthorized</b> message.
  * The account ID, Org ID, and CID (correlation identifer) are parsed from the account token.

## Request body

- CreateOnUsDisputeRequest
  - `source_identifier` SourceIdentifier, required
    - `id` string: On-Us source ID - authorization or transaction ID depending on `type`.
    - `type` 'AUTHORIZATION' | 'TRANSACTION': On-Us dispute type
  - `modality` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8, required: On-us issuer reason code: * `1` - Services not provided or product not received<br /> * `2` - Defective product or not as described<br /> * `3` - Nonexistent card number / Closed or nonexistent account<br /> * `4` - Authorization denied / No authorization<br /> * `5` - Fraud - Card present<br /> * `6` - Fraud - Card not present<br /> * `7` - Duplicate processing<br /> * `8` - Processing error
  - `is_partial` boolean, required: Is partial amount chargeback? Default is `false`.
  - `disputed_amount` number, required: Disputed amount.
  - `comment` string, nullable: Client custom dispute comment.
  - `protocol` string: Client custom protocol ID. This is primarily for you to internally identify a request. If not provided, Pismo creates a CID (correlation ID) field for this purpose.
  - `metadata` Metadata: Can be used for caller's dispute information and process. Objects and name-value pairs. **Note**: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to [Get started with Pismo APIs](ref:get-started-with-pismo-apis#metadata).

## Response `201`

Dispute Created

- CreateOnUsDisputeResponse: Create On-Us dispute request body
  - `dispute_id` number: Dispute ID
  - `dispute_status` OnUsDisputeStatusObject: On-Us dispute status information
    - `description` string: Description status - enums for a client's state machine, not to be implemented for anyone else at this point.
    - `type` 'PRIMITIVE_ON_US': Type status ID.
    - `group` 'OPEN' | 'APPROVED' | 'DENIED' | 'CARDNETWORK_CHARGEBACK' | 'ANALYSING' | 'CARDNETWORK_SECOND_PRESENTMENT' | 'FAILED' | 'CARDNETWORK_PREARBITRATION' | 'RESEND' | 'LOSS' | 'WON' | 'REJECTED' | 'FAILED_PROCESSED': Group status enums
  - `dispute_reason` DisputeReasonObject: Dispute reason information
    - `id` number: Dispute reason ID.
    - `description` string: Dispute reason description
    - `reason_code` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8: On-us issuer reason code: * `1` - Services not provided or product not received<br /> * `2` - Defective product or not as described<br /> * `3` - Nonexistent card number / Closed or nonexistent account<br /> * `4` - Authorization denied / No authorization<br /> * `5` - Fraud - Card present<br /> * `6` - Fraud - Card not present<br /> * `7` - Duplicate processing<br /> * `8` - Processing error
    - `type` 'ON_US': Dispute reason type
  - `source` SourceIdentifier
    - `id` string: On-Us source ID - authorization or transaction ID depending on `type`.
    - `type` 'AUTHORIZATION' | 'TRANSACTION': On-Us dispute type
  - `disputed_amount` number: Disputed amount.
  - `is_partial` boolean: Is partial amount chargeback? Default is `false`.
  - `account_id` number: Pismo account ID
  - `comment` string, nullable: Client custom dispute comment.
  - `protocol` string: Client custom protocol ID. This is primarily for you to internally identify a request. If not provided, Pismo creates a CID (correlation ID) field for this purpose.
  - `metadata` Metadata: Can be used for caller's dispute information and process. Objects and name-value pairs. **Note**: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to [Get started with Pismo APIs](ref:get-started-with-pismo-apis#metadata).
  - `created_at` string: Created at datetime, format = yyyy-mm-dd hh:mm:ss"
  - `created_at_utc` string, date-time: Dispute created in UTC date/time.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `404`: Not found
- `422`: Unprocessable entity
- `500`: Internal server error
- `504`: Gateway timeout

---

[API](https://skmtc.dev/pismo/apis/card-issuing-disputes.md) - [All operations](https://skmtc.dev/pismo/apis/card-issuing-disputes/llms.txt) - [OpenAPI document](https://skmtc.dev/pismo/apis/card-issuing-disputes/revisions/53592b5468b6?raw)