m2pfintech
API LibraryDispute

Raise a Dispute

Raises a formal dispute for a specific transaction on behalf of a cardholder. The dispute is submitted to the card network for investigation and resolution.

How It Works

  1. Identify the Transaction: Get the transaction details from the Transaction History API
  2. Select Reason Code: Use the Fetch Reason Codes API to get applicable codes for the card network
  3. Submit Dispute: Call this API with the transaction details and reason code
  4. Track Status: A complaint ID is returned for tracking; use webhooks for status updates

Key Business Rules

  • Each transaction can only be disputed once (duplicate disputes are rejected)
  • The reasonId must be valid for the card's network type
  • The customerIdentificationId should be the cardholder's entity ID or unique customer ID
  • Transaction details (transactionDtls) must include the original transaction identifier (tranId)
  • The dispute amount can be equal to or less than the original transaction amount
  • Disputes must be raised within the network-specific time limit (typically 120 days from transaction)

Required Fields in Transaction Details

The transactionDtls object requires at minimum:

  • tranId: Original transaction ID (from transaction history)
  • tranAmt: Original transaction amount
  • disputeAmt: Amount being disputed (≤ transaction amount)
  • custMobile: Cardholder's mobile number
  • entityId: Cardholder's entity ID
  • kitNo: Card kit number
POST
/v1/disputes/

Authorization

bearerAuth tenantId
AuthorizationBearer <token>

JWT Bearer token from the Authentication API

In: header

X-TENANT-ID<token>

Your unique tenant identifier assigned during onboarding

In: header

Header Parameters

X-TENANT-ID*string

Your unique tenant identifier

Request Body

application/json

Dispute details including reason code and original transaction information

customerIdentificationId*string

Required. The entity ID or unique customer identifier of the cardholder filing the dispute. This links the dispute to the correct customer record.

Length1 <= length
description?string

Free-text description of the dispute from the cardholder's perspective. Include details like what happened, when it was noticed, and any communication with the merchant.

reasonId*integer

Required. The reason code ID from the Fetch Reason Codes API. Must be a valid reason code for the specified network. Example: 40 for "Merchandise/Services Not Received" (VISA).

networkId*integer

Required. The card network identifier: 1=VISA, 2=RuPay, 3=UPI, 4=NETC, 5=NFS, 6=Mastercard. Must match the network of the card used in the original transaction.

Value in1 | 2 | 3 | 4 | 5 | 6
incomingTicketId?string

Optional external ticket/reference number from your helpdesk or CRM system. Useful for cross-referencing the dispute with your internal support workflow.

complaintId?string

Complaint identifier associated with the dispute

status?string

Current status of the dispute

transactionDtls*

Required. Details of the original transaction being disputed. Most fields can be obtained from the Transaction History API response.

referenceTransactionDtls?

Reference transactions related to the dispute (e.g., partial refunds)

clientId?string

Client identifier for the dispute

disputeNetworkConf?string

Card network configuration for the dispute

Value in"VISA" | "RUPAY" | "UPI" | "NFS" | "NETC" | "MASTERCARD"
enableNewReconPayload?boolean

Set to true to use the enhanced reconciliation payload format. Recommended for new integrations.

mobileNumber?

Cardholder's mobile number (optional, for additional validation)

id?string

Response Body

application/json

application/json

application/json

curl -X POST "https://sandbox-api.m2pprepaid.com/prepaid/corporate/v1/disputes/" \  -H "X-TENANT-ID: ACME_CORP" \  -H "Content-Type: application/json" \  -d '{    "customerIdentificationId": "798782647420001622070825",    "description": "Paid at store but goods were never delivered",    "reasonId": 40,    "networkId": 1,    "incomingTicketId": "TICKET_2024_001",    "enableNewReconPayload": true,    "transactionDtls": {      "entityId": "798782647420001622070825",      "kitNo": "910000031",      "tranId": "702959034",      "tranAmt": "2500.00",      "disputeAmt": "2500.00",      "disputeCurrency": "356",      "transactionCurrency": "356",      "channel": "POS",      "merchantName": "ABC Electronics Store",      "custMobile": "9876543210",      "custEmailId": "rajesh.kumar@email.com",      "txnOn": "2025-01-15 10:30:00",      "maskedCardNumber": "5231XXXXXXXX0015",      "rrn": "682246275971"    }  }'
{
  "result": [
    {
      "id": 136,
      "complaintId": "24112515053662",
      "disputeAmount": "2500.00",
      "disputeCurrency": "356",
      "reasonId": 40,
      "networkId": 1,
      "actionEntry": 1,
      "expiryDate": "2026-02-22 09:35:36",
      "raisedDate": "2025-11-24 09:35:36"
    }
  ],
  "pagination": null
}
{
  "type": "https://www.m2pfintech.com/problem/problem-with-message",
  "title": "Bad Request",
  "status": 400,
  "detail": "customerIdentificationId: must not be empty",
  "message": "error.http.400"
}

A dispute has already been raised for this transaction

{
  "type": "https://www.m2pfintech.com/problem/problem-with-message",
  "title": "Duplicate Dispute Transaction Registration Attempt!",
  "status": 409,
  "detail": "Duplicate Dispute Transaction Registration Attempt!",
  "message": "error.business",
  "businessCode": "50009"
}

Fetch Dispute Reason Codes by Network GET

Retrieves dispute reason codes filtered by a specific card network. Use this endpoint when you know the card network (VISA, RuPay, Mastercard, etc.) and want to show only the applicable reason codes. ### Network IDs | ID | Network | |----|---------| | 1 | VISA | | 2 | RuPay | | 3 | UPI | | 4 | NETC (FASTag) | | 5 | NFS (ATM) | | 6 | Mastercard |

Calculate Forex Fee Summary POST

Calculates and returns a detailed fee breakdown for forex card operations. Use this API to preview all applicable fees, taxes, and the total payable amount **before** initiating an issuance, load, or reload transaction. ### How It Works 1. Specify which fee types to include (issuance, load, reload, etc.) using boolean flags 2. Provide the hierarchy ID (your corporate/branch identifier) and product details 3. The API calculates all applicable fees based on your configured fee structure 4. Returns a comprehensive breakdown including net value, fees, taxes, TCS, and total amount ### Key Business Rules - Fee structures are configured per hierarchy (corporate/branch level) - Product type and load amount affect the fee calculation - Promotional codes can modify fee structures if configured - Fee waiver flag allows authorized users to waive fees for specific transactions - Conversion GST is calculated on the forex markup and returned separately ### Common Use Cases | Scenario | Flags to Set | |----------|-------------| | New card issuance with initial load | `issuanceFeeApplied=true`, `loadFeeApplied=true`, `conversionGstApplied=true` | | Subsequent reload | `reLoadFeeApplied=true`, `conversionGstApplied=true` | | Card replacement | `cardReplacementFeeApplied=true` | | Card closure with pullback | `cardClosureFeeApplied=true`, `pullbackFeeApplied=true` |