m2pfintech
API LibraryForex

Calculate Forex Fee Summary

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

ScenarioFlags to Set
New card issuance with initial loadissuanceFeeApplied=true, loadFeeApplied=true, conversionGstApplied=true
Subsequent reloadreLoadFeeApplied=true, conversionGstApplied=true
Card replacementcardReplacementFeeApplied=true
Card closure with pullbackcardClosureFeeApplied=true, pullbackFeeApplied=true
POST
/v1/forex/summary/fee

Authorization

bearerAuth tenantId
AuthorizationBearer <token>

JWT Bearer token obtained from the Authentication API. Include in the Authorization header as: Bearer <your-token>

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 assigned during partner onboarding. This determines your fee configuration, product catalog, and hierarchy structure.

Request Body

application/json

Fee calculation request specifying which fee components to include and the product/hierarchy details for fee lookup.

issuanceFeeApplied?boolean

Set to true to include the one-time card issuance fee in the calculation. Applicable when issuing a new forex card.

loadFeeApplied?boolean

Set to true to include the initial load fee. Applicable when loading currency onto a newly issued card for the first time.

reLoadFeeApplied?boolean

Set to true to include the reload fee. Applicable for subsequent currency loads after the initial issuance load.

backupCardFeeApplied?boolean

Set to true to include the backup card fee. Applicable when issuing a secondary backup card alongside the primary forex card.

pullbackFeeApplied?boolean

Set to true to include the pullback fee. Applicable when reversing a load transaction or pulling back remaining balance from the card (e.g., during card surrender).

cardReplacementFeeApplied?boolean

Set to true to include the card replacement fee. Applicable when replacing a lost, stolen, or damaged forex card with a new one.

conversionGstApplied?boolean

Set to true to include the GST on currency conversion markup. This is the tax charged on the forex conversion spread/margin. Typically set to true for all transactions involving currency conversion.

cardClosureFeeApplied?boolean

Set to true to include the card closure fee. Applicable when the cardholder surrenders/closes the forex card permanently.

feeDto*

Contains the hierarchy (corporate/branch) and product details used to look up the applicable fee structure. Fee structures are configured at the hierarchy level during partner onboarding.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://sandbox-api.m2pprepaid.com/prepaid/corporate/v1/forex/summary/fee" \  -H "X-TENANT-ID: ACME_FOREX" \  -H "Content-Type: application/json" \  -d '{    "issuanceFeeApplied": true,    "loadFeeApplied": true,    "reLoadFeeApplied": false,    "backupCardFeeApplied": false,    "pullbackFeeApplied": false,    "cardReplacementFeeApplied": false,    "conversionGstApplied": true,    "cardClosureFeeApplied": false,    "feeDto": {      "hierarchyId": "CORP_001",      "type": "Corporate",      "feeWaiver": false,      "products": [        {          "productId": "FOREX_USD_CARD",          "loadAmount": 85000,          "type": "Forex"        }      ]    }  }'

Complete fee breakdown for a new forex card issuance with initial load of 85,000 in local currency

{
  "result": {
    "issuanceFeeResponseDto": {
      "netValue": 85000,
      "totalFees": 200,
      "taxAmount": 36,
      "totalAmount": 85236,
      "totalTaxAndFees": 236,
      "gstPercentage": 18
    },
    "loadFeeResponseDto": {
      "netValue": 85000,
      "totalFees": 150,
      "taxAmount": 27,
      "totalAmount": 85177,
      "totalTaxAndFees": 177,
      "gstPercentage": 18
    },
    "reLoadFeeResponseDto": null,
    "backupCardFeeResponseDto": null,
    "pullbackFeeResponseDto": null,
    "cardReplacementFeeResponseDto": null,
    "cardClosureFeeResponseDto": null,
    "conversionGst": 45,
    "netValue": 85000,
    "totalFees": 350,
    "taxAmount": 108,
    "totalAmount": 85458,
    "totalTaxAndFees": 458,
    "tcsAmount": 4250
  },
  "pagination": null
}

{
  "type": "https://www.m2pfintech.com/problem/problem-with-message",
  "title": "Bad Request",
  "status": 400,
  "detail": "hierarchyId: must not be blank",
  "message": "error.http.400"
}

The hierarchy ID provided does not exist in the system

{
  "type": "https://www.m2pfintech.com/problem/problem-with-message",
  "title": "Corporate/Branch does not exist for id: INVALID_123",
  "status": 409,
  "detail": "Corporate/Branch does not exist for id: INVALID_123",
  "message": "error.business",
  "businessCode": "PP_CORP_002"
}

{
  "type": "https://www.m2pfintech.com/problem/problem-with-message",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred while calculating fees",
  "message": "error.http.500"
}

Raise a Dispute POST

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

Fetch Multi FX Rates POST

Retrieves conversion rates for multiple wallet currencies in a single call. Use this when loading a forex card with multiple currencies (e.g., USD + EUR + GBP) to get all rates at once. ### Request - Provide a list of wallet names in `walletList` - Specify `amount` for rate calculation - Use `fundMode` to indicate LOAD, RELOAD, or REFUND ### Response Returns an array of conversion rate objects, one per wallet currency.