PIpismo
On-Us

Create on-us dispute

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 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 guide.

This endpoint generates a On-us dispute created 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.
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

Request body

modality1 | 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_partialboolean required

Is partial amount chargeback? Default is false.

disputed_amountnumber required

Disputed amount.

commentstring nullable

Client custom dispute comment.

protocolstring

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.

metadataMetadata

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.

Example request

{
  "source_identifier": {
    "id": "10001011169",
    "type": "AUTHORIZATION"
  },
  "modality": 2,
  "disputed_amount": 10,
  "comment": "Custom comment",
  "protocol": "20251128111532456",
  "metadata": {
    "field1": "value",
    "field2": "value"
  }
}

Response

Dispute Created

dispute_idnumber

Dispute ID

disputed_amountnumber

Disputed amount.

is_partialboolean

Is partial amount chargeback? Default is false.

account_idnumber

Pismo account ID

commentstring nullable

Client custom dispute comment.

protocolstring

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.

metadataMetadata

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.

created_atstring

Created at datetime, format = yyyy-mm-dd hh:mm:ss"

created_at_utcstring date-time

Dispute created in UTC date/time.

Example response

{
  "dispute_id": 48670,
  "dispute_status": {
    "description": "PENDING",
    "type": "PRIMITIVE_ON_US",
    "group": "OPEN"
  },
  "dispute_reason": {
    "id": 58,
    "description": "Services not provided or product not received",
    "reason_code": 2,
    "type": "ON_US"
  },
  "source": {
    "id": "10001011169",
    "type": "AUTHORIZATION"
  },
  "disputed_amount": 10,
  "account_id": 577830,
  "comment": "Custom comment",
  "protocol": "20251128111532456",
  "metadata": {
    "field1": "value",
    "field2": "value"
  },
  "created_at": "2024-10-18 11:21:45",
  "created_at_utc": "2021-02-21T22:51:43.000000000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.