Skip to main content

Create and update external disputes

note

transactionId and disputeId in these examples are placeholders — use real ids from paymentExternalTransactions / paymentExternalDisputes.

Use the paymentExternalDisputeCreate and paymentExternalDisputeUpdate mutations to record and update the disputes of an external payment gateway in OMS.

A dispute is always linked to a transaction, never directly to an order: to find the order a dispute affects, traverse its externalTransaction and, from there, the transaction's order — see From transactions and disputes to the order.

Create an external dispute​

Use paymentExternalDisputeCreate mutation to add a new dispute to OMS. The mutation accepts a PaymentExternalDisputeCreateInput object — its reference lists all the available fields.

Use it when the payment provider opens a chargeback, claim or similar dispute against a payment recorded in OMS.

Field notes:

  • transactionId is the disputed transaction; number is the dispute identifier assigned by the provider.
  • amount is negative.
  • status is one of the dispute statuses.
  • defenseEndAt is the merchant defense deadline, cleared automatically when the dispute reaches a final status.
Request
mutation createExternalDispute {
  paymentExternalDisputeCreate(
    input: {
      transactionId: "1005"
      number: "12345"
      amount: -10.1
      currency: "EUR"
      reason: "Items not delivered"
      status: pended
      defenseEndAt: "2026-12-03T10:15:30.000Z"
    }
  ) {
    id
  }
}
Open in playground
Response
{
  "data": {
    "paymentExternalDisputeCreate": {
      "id": "12"
    }
  },
  "extensions": {
    "queryComplexity": 2,
    "bucketBalance": 9998,
    "bucketRestoreRate": 100
  }
}

Update an external dispute​

Use paymentExternalDisputeUpdate mutation to update an existing dispute in OMS. The mutation accepts a PaymentExternalDisputeUpdateInput object — its reference lists all the available fields.

It updates the status, the provider reason or the defense deadline of an existing dispute.

Field notes:

  • status transitions are validated: an invalid one (including the status the dispute already has) is rejected with Invalid status update and the error code BAD_REQUEST. The allowed transitions are listed in Dispute statuses.
  • defenseEndAt can be updated while the dispute is active; it is cleared when the dispute reaches a final status.
Request
mutation updateExternalDispute {
  paymentExternalDisputeUpdate(
    disputeId: "12"
    input: {
      status: closed
      reason: "Cancelled"
    }
  ) {
    id
  }
}
Open in playground
Response
{
  "data": {
    "paymentExternalDisputeUpdate": {
      "id": "12"
    }
  },
  "extensions": {
    "queryComplexity": 2,
    "bucketBalance": 9998,
    "bucketRestoreRate": 100
  }
}

Relevant permissions

The operations in this page require the following permissions on the API credentials — they are configured for you by Calicantus.

  • payment_dispute:mutation:payment_external_dispute_create
  • payment_dispute:mutation:payment_external_dispute_update
  • payment_dispute:read