---
updatedAt: 2026-04-22T15:15:32.000Z
---
Fetch the complete documentation index at: https://developers.pismo.io/pismo-docs/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.
# Create dispute fee
A dispute fee, or *fee collection* in network terminology, is a way for an acquirer and issuer to exchange money outside the normal chargeback process. Typically, this means reversing a settled chargeback, but not always,
You can use this endpoint to create a dispute fee with or without a chargeback claim ID. You can create a dispute fee for a claim that already exists or, if it doesn't, you can pass the necessary authorization information to create it.
For more information, refer to [Dispute fees](doc:disputes-overview#dispute-fees) in the Disputes overview guide. This feature is only available for Mastercard and Elo.
This endpoint generates a [Dispute fee status created](https://developers.pismo.io/events/docs/disputes-dispute-fee-events-1) event.
**Note:** This endpoint takes an account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a 401 Unauthorized message.
# OpenAPI definition
```json
{
"openapi": "3.0.1",
"info": {
"title": "Card issuing - Disputes",
"version": "1.0.0",
"description": "Disputes API endpoints",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support/"
},
"license": {
"name": "Copyright Pismo"
}
},
"servers": [
{
"url": "https://sandbox.pismolabs.io/disputes",
"description": "Sandbox API server for testing"
}
],
"security": [
{
"BearerAuth": []
}
],
"tags": [
{
"name": "Fees",
"description": "Endpoints to create and check status for fees"
}
],
"components": {
"parameters": {
"AuthHeader": {
"in": "header",
"name": "Authorization",
"required": true,
"description": "Account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a 401 Unauthorized message.",
"schema": {
"type": "string",
"example": "Bearer eyJhbGci...IUzUx"
}
}
},
"schemas": {
"CardID": {
"type": "number",
"description": "Pismo card ID.",
"example": 123456
},
"CreatedAtUTC": {
"type": "string",
"description": "Dispute created in UTC date/time.",
"format": "date-time",
"example": "2021-02-21T22:51:43.000000000Z"
},
"CreditSender": {
"type": "boolean",
"default": false,
"description": "Credit the sender? Default is `false`."
},
"DisputeFee": {
"type": "object",
"required": [
"amount",
"card_id",
"credit_sender",
"credit_receiver",
"currency",
"destination_member",
"fee_date",
"network_brand_type",
"reason_code"
],
"description": "Dispute fee object",
"properties": {
"amount": {
"type": "number",
"example": 100,
"format": "double",
"description": "Fee amount."
},
"card_id": {
"$ref": "#/components/schemas/CardID"
},
"credit_sender": {
"type": "boolean",
"default": false,
"description": "Credit the sender? Default is `false`."
},
"credit_receiver": {
"type": "boolean",
"default": false,
"description": "Credit the receiver? Default is `false`."
},
"currency": {
"type": "string",
"maxLength": 3,
"example": "USD",
"description": "ISO 4217 fee currency code."
},
"destination_member": {
"type": "string",
"example": "002083",
"maxLength": 6,
"description": "Destination member for the fee collection. These values are known to the network and identify either the issuer or acquirer."
},
"fee_date": {
"type": "string",
"example": "2021-02-15",
"maxLength": 10,
"format": "date",
"description": "Date the fee was attached to the claim, format = yyyy-mm-dd."
},
"network_brand_type": {
"$ref": "#/components/schemas/NetworkBrand"
},
"reason_code": {
"type": "string",
"maxLength": 4,
"example": "7604",
"description": "Collection reason code. These codes can be found in Mastercard's [Global Clearing Management System Reference Manual](https://pismoassets.pismo.io/pismo-docs/mc_gcms_rm.pdf) starting on page 408.\n"
},
"authorization_id": {
"type": "number",
"description": "Authorization ID. **REQUIRED** if `claim_id` and `arn` is not passed."
},
"arn": {
"type": "string",
"description": "Acquirer reference number. **REQUIRED** if `claim_id` is not passed.",
"example": "1564984"
},
"transaction_amount": {
"type": "number",
"description": "Transaction amount. **REQUIRED** if `claim_id` is not passed.",
"format": "double",
"example": 100
},
"transaction_date": {
"type": "string",
"description": "Transaction date, format = yyyy-mm-dd hh:mm:ss. **REQUIRED** if `claim_id` is not passed.",
"format": "date-time",
"example": "2022-06-01 10:25:36"
},
"claim_id": {
"type": "string",
"description": "Fee item claim ID",
"example": "121698491",
"maxLength": 19
},
"card_acceptor_code": {
"type": "string",
"maxLength": 15,
"example": "Test1234",
"description": "Merchant ID associated with this fee collection, if any."
},
"country_code": {
"type": "string",
"maxLength": 3,
"example": "USA",
"description": "ISO 3166 3-letter country code."
},
"message": {
"type": "string",
"maxLength": 100,
"example": "Cardholder recognized the transaction",
"description": "Message regarding fee - 100 chars maximum."
},
"settlement_date": {
"type": "string",
"description": "Settlement date, format = yyyy-mm-dd.",
"example": "2021-09-22",
"format": "date",
"maxLength": 10
},
"reply_fee_id": {
"type": "string",
"maxLength": 19,
"example": "300009520876",
"description": "Fee ID to be sent in reply to created Fee."
},
"control_number": {
"type": "string",
"description": "Control number. Used in routing chargeback and retrieval documentation - either a MasterCom endpoint suffix, in case of 2 characters, or a full MasterCom endpoint in case of 7 characters. When MasterCom control number is present, it cannot be all spaces or all zeros.\n",
"maxLength": 7,
"example": "1589457"
}
},
"x-examples": {
"With claim ID": {
"card_id": 123456,
"claim_id": "12345981232",
"card_acceptor_code": "Test1234",
"country_code": "USA",
"destination_member": "002083",
"fee_date": "yyyy-MM-dd",
"currency": "USD",
"amount": "100.00",
"message": "This is a test message",
"reason_code": "7604",
"settlement_date": "2024-08-09",
"control_number": "1589457",
"credit_sender": false,
"credit_receiver": false,
"network_brand_type": "VISA"
},
"Without claim id": {
"authorization_id": 123456,
"arn": "1564984",
"transaction_amount": "100.00",
"transaction_date": "2022-06-01 10:25:36",
"card_id": 123456,
"card_acceptor_code": "Test1234",
"country_code": "USA",
"destination_member": "002083",
"fee_date": "2024-12-03",
"currency": "USD",
"amount": "100.00",
"message": "This is a test message",
"reason_code": "7604",
"settlement_date": "2024-04-12",
"control_number": "1589457",
"credit_sender": false,
"credit_receiver": false,
"network_brand_type": "VISA"
},
"With reply fee ID": {
"card_id": 123456,
"claim_id": "121698491",
"card_acceptor_code": "Test1234",
"country_code": "USA",
"destination_member": "002083",
"fee_date": "2024-03-09",
"currency": "USD",
"amount": "100.00",
"message": "This is a test message",
"reason_code": "7604",
"settlement_date": "2024-10-09",
"reply_fee_id": "300009520876",
"control_number": "1589457",
"credit_sender": false,
"credit_receiver": false,
"network_brand_type": "VISA"
}
}
},
"DisputeFeeResponse": {
"type": "object",
"description": "Dispute fee response object",
"properties": {
"id": {
"type": "number",
"description": "Dispute fee ID",
"example": 152
},
"arn": {
"type": "string",
"description": "Acquirer reference number. **REQUIRED** if `claim_id` is not passed.",
"example": "1564984"
},
"transaction_amount": {
"type": "number",
"description": "Transaction amount. **REQUIRED** if `claim_id` is not passed.",
"format": "double"
},
"transaction_date": {
"type": "string",
"description": "Transaction date, format = yyyy-mm-dd hh:mm:ss. **REQUIRED** if `claim_id` is not passed.",
"format": "date-time",
"example": "2022-06-01 10:25:36"
},
"card_id": {
"$ref": "#/components/schemas/CardID"
},
"card_acceptor_code": {
"type": "string",
"maxLength": 15,
"example": "Test1234",
"description": "Merchant ID associated with this fee collection..if any."
},
"country_code": {
"type": "string",
"maxLength": 3,
"example": "USA",
"description": "ISO country code."
},
"destination_member": {
"type": "string",
"example": "002083",
"maxLength": 6,
"description": "Destination member for the fee collection. These values are known to the network and identify either the acquirer or issuer."
},
"fee_date": {
"type": "string",
"example": "2021-02-15",
"maxLength": 10,
"format": "date",
"description": "Date the fee was attached to the claim, format = yyyy-mm-dd"
},
"currency": {
"type": "string",
"maxLength": 3,
"example": "USD",
"description": "ISO 4217 currency code."
},
"amount": {
"type": "number",
"example": 100,
"format": "double",
"description": "Fee amount."
},
"message": {
"type": "string",
"maxLength": 100,
"example": "Cardholder recognized transaction",
"description": "Message regarding fee - 100 chars maximum."
},
"reason_code": {
"type": "string",
"maxLength": 4,
"example": "7604",
"description": "Collection reason code. These codes can be found in Mastercard's [Global Clearing Management System Reference Manual](https://pismoassets.pismo.io/pismo-docs/mc_gcms_rm.pdf) starting on page 408.\n"
},
"settlement_date": {
"type": "string",
"description": "Settlement date, format = yyyy-mm-dd.",
"example": "2021-09-22",
"format": "date",
"maxLength": 10
},
"control_number": {
"type": "string",
"description": "Control number",
"maxLength": 7,
"example": "1589457"
},
"credit_sender": {
"$ref": "#/components/schemas/CreditSender"
},
"credit_receiver": {
"$ref": "#/components/schemas/CreditReceiver"
},
"network_brand_type": {
"$ref": "#/components/schemas/NetworkBrand"
},
"status": {
"type": "string",
"description": "Dispute fee status - `PENDING`, `PROCESSED`, or `FAILED`.",
"enum": [
"PENDING",
"PROCESSED",
"FAILED"
],
"example": "PENDING"
},
"chargeback_ref_num": {
"type": "string",
"description": "Chargeback reference number",
"maxLength": 100,
"example": "9000000006"
},
"reconciliation_amount": {
"type": "number",
"description": "Reconciliation amount",
"format": "double",
"example": 123.22
},
"reconciliation_currency": {
"type": "string",
"description": "Reconciliation currency",
"example": "EUR",
"maxLength": 3
},
"japan_common_merchant_code": {
"type": "string",
"description": "Japanese common merchant codes",
"example": "0410",
"maxLength": 100
},
"installment_data": {
"type": "string",
"description": "Installment data",
"example": "1234567890",
"maxLength": 255
},
"reply_fee_id": {
"type": "string",
"maxLength": 19,
"example": "300009520876",
"description": "Fee ID to send to reply to created fee."
},
"reject_reason": {
"type": "string",
"description": "Reject reason",
"maxLength": 515,
"example": "Code1=0142(00):D0063/002;DE072=D0063\\\\\\\\\\\\\\\\8000000808\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ "
},
"created_at": {
"type": "string",
"description": "When dispute created, format = yyyy-mm-ddThh:mm:ss\"",
"example": "2222-10-07T11:21:45"
},
"updated_at": {
"$ref": "#/components/schemas/UpdatedAt"
},
"created_at_utc": {
"$ref": "#/components/schemas/CreatedAtUTC"
},
"updated_at_utc": {
"$ref": "#/components/schemas/UpdatedAtUTC"
}
}
},
"NetworkBrand": {
"type": "string",
"example": "Visa",
"description": "Network brand",
"enum": [
"Visa",
"Mastercard",
"Elo"
]
},
"UpdatedAt": {
"type": "string",
"description": "Datetime when updated, format = yyyy-mm-dd hh:mm:ss",
"example": "2024-10-18 11:21:45"
},
"UpdatedAtUTC": {
"type": "string",
"description": "When dispute updated in UTC date/time.",
"example": "2022-10-13T19:56:010000000Z"
},
"CreditReceiver": {
"type": "boolean",
"description": "Should receiver be credited?"
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Account access token. Tokens can expire quickly, which can result in an \"Unauthorized\" error.",
"bearerFormat": "JWT"
}
},
"responses": {
"400BadRequest": {
"description": "Bad Request"
},
"401Unauthorized": {
"description": "Unauthorized. Invalid or missing access token."
},
"422UnprocessableEntity": {
"description": "Unprocessable entity"
},
"500InternalServerError": {
"description": "Internal server error"
}
}
},
"paths": {
"/v1/fee": {
"post": {
"summary": "Create dispute fee",
"operationId": "post-v1-fee",
"description": "A dispute fee, or *fee collection* in network terminology, is a way for an acquirer and issuer to exchange money outside the normal chargeback process. Typically, this means reversing a settled chargeback, but not always,\n\nYou can use this endpoint to create a dispute fee with or without a chargeback claim ID. You can create a dispute fee for a claim that already exists or, if it doesn't, you can pass the necessary authorization information to create it.\n\nFor more information, refer to [Dispute fees](https://developers.pismo.io/pismo-docs/docs/disputes-overview#dispute-fees) in the Disputes overview guide. This feature is only available for Mastercard and Elo.\n\nThis endpoint generates a [Dispute fee status created](https://developers.pismo.io/events/docs/disputes-dispute-fee-events-1) event.\n\n**Note:** This endpoint takes an account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a 401 Unauthorized message.\n",
"tags": [
"Fees"
],
"parameters": [
{
"$ref": "#/components/parameters/AuthHeader"
}
],
"requestBody": {
"description": "Dispute fee data",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisputeFee"
},
"examples": {
"Dispute fee with clam id": {
"value": {
"card_id": 15595,
"claim_id": "15465165165",
"card_acceptor_code": "125",
"country_code": "125",
"destination_member": "125485",
"fee_date": "2022-05-31",
"currency": "840",
"amount": 15.56,
"message": "test",
"reason_code": "1515",
"settlement_date": "2022-05-31",
"control_number": "1564989",
"credit_sender": false,
"credit_receiver": true,
"network_brand_type": "Mastercard"
}
},
"Dispute fee when there is no claim id": {
"value": {
"authorization_id": 31241,
"arn": "15641616",
"transaction_amount": 36.25,
"transaction_date": "2022-05-31 23:00:25",
"card_id": 15595,
"card_acceptor_code": "125",
"country_code": "125",
"destination_member": "125485",
"fee_date": "2022-05-31",
"currency": "840",
"amount": 15.56,
"message": "test",
"reason_code": "1515",
"settlement_date": "2022-05-31",
"reply_fee_id": "1949884",
"control_number": "1564989",
"credit_sender": false,
"credit_receiver": true,
"network_brand_type": "Mastercard"
}
},
"Dispute fee with replay ID": {
"value": {
"card_id": 15595,
"claim_id": "15465165165",
"card_acceptor_code": "125",
"country_code": "125",
"destination_member": "125485",
"fee_date": "2022-05-31",
"currency": "840",
"amount": 15.56,
"message": "test",
"reason_code": "1515",
"settlement_date": "2022-05-31",
"reply_fee_id": "12345645",
"control_number": "1564989",
"credit_sender": false,
"credit_receiver": true,
"network_brand_type": "Mastercard"
}
}
}
},
"application/xml": {
"schema": {
"type": "object",
"properties": {}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisputeFeeResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"422": {
"$ref": "#/components/responses/422UnprocessableEntity"
},
"500": {
"$ref": "#/components/responses/500InternalServerError"
}
}
}
}
}
}
```