Debit Forex Card (Partial Withdrawal)
Debits (withdraws) a specific amount from a forex card wallet. The withdrawn amount is credited back to the customer's bank account.
When to Use
- Customer wants to withdraw unused forex after a trip
- Partial encashment of forex card balance
- Fund reallocation between wallets (debit one, credit another)
Key Difference from Debit-Closure
This is a partial debit — the card and wallet remain active after the transaction. For full withdrawal with card closure, use the Debit with Closure endpoint.
Authorization
bearerAuth tenantId JWT Bearer token from the Authentication API
In: header
Your unique tenant identifier assigned during onboarding
In: header
Header Parameters
Your unique tenant identifier
Request Body
application/json
Required. Branch/corporate hierarchy ID
1 <= lengthRequired. Card kit number associated with the particular card/product
1 <= lengthUnique entity identifier for the transaction associated with the customer
Customer's mobile number
Full name of the customer
Encrypted Card Number of the customer
Unique customer identifier
Type of card issued; Single for single-user, Bulk for bulk issuance
"Single" | "Bulk"Transaction amount in the wallet currency
0 <= valueDescription or remarks for the transaction
Required. CREDIT for loading, DEBIT for withdrawal
"CREDIT" | "DEBIT"Indicates partial or full debit transaction
"PARTIAL_DEBIT" | "FULL_DEBIT" | "FULL_DEBIT_WITH_CLOSURE"Product details associated with the transaction
Wallet details used for the transaction
Trip details (required for CREDIT operations)
Funding source details
List of wallet amounts and conversion details (for multi-wallet operations)
Summary of transaction including fees, GST, TCS, etc.
Reason for fee waiver approval, if any
Declarations such as FATCA, ITR, T&C, LRS
Branch code or hierarchy ID where the transaction occurred
Teller ID who processed the transaction
Retrieval Reference Number for the transaction
Indicates which channel this transaction is initiated from
Indicates if transaction is initiated from a branch
Indicates if maker-checker workflow is enabled for this transaction
Loan details if applicable; mandatory if purpose of travel is EDUCATIONAL_LOAN_LETTER
Custom attributes for additional data
Required when feeWaiver = ALLOWED. Upload the approval document using the
file upload API and pass the returned fileName and filePath here.
The platform validates the document exists before processing the transaction.
Ignored when feeWaiver = NOTALLOWED.
"SUCCESS" | "FAILED" | "CREATED""SUCCESS" | "FAILURE"Response Body
application/json
application/json
application/json
curl -X POST "https://sandbox-api.m2pprepaid.com/prepaid/customer/v1/forex/card-holder-loads/debit" \ -H "X-TENANT-ID: ACME_CORP" \ -H "Content-Type: application/json" \ -d '{ "hierarchyId": "90009", "kitNo": "320000541", "entityId": "476843769320000541160925", "mobile": { "value": "9876543210", "countryCode": 91 }, "amount": 200, "transactionType": "DEBIT", "debitTransactionType": "PARTIAL_DEBIT", "product": { "productId": "FRX001", "productType": "FOREX" }, "wallet": { "accountId": "c515d3a6-6c51-4f64-bd7b-d9cbd9c5b22f" } }'{
"result": {},
"pagination": {
"list": true,
"pageSize": 0,
"pageNo": 0,
"totalPages": 0,
"totalElements": 0
}
}{
"type": "https://www.m2pfintech.com/problem/problem-with-message",
"title": "Bad Request",
"status": 400,
"detail": "Unable to convert http message",
"message": "error.http.400"
}{
"type": "https://www.m2pfintech.com/problem/problem-with-message",
"title": "Customer does not exist",
"status": 409,
"detail": "Customer does not exists for id",
"message": "error.business",
"businessCode": "PPCUST_002"
}Credit Forex Card POST
Loads forex currency onto a cardholder's forex card wallet. This is used for initial loading and reloading of forex cards. ### Integration Sequence (follow in order) 1. **Fetch conversion rate** — `POST /v1/forex/conversion-rate` — returns per-wallet `conversionRate`, `baseConversionRate`, `netAmount`, `baseConvertedAmount`, `discountRate`, `discountAmount`, `conversionGst`, `valueOfSupply`. 2. **Fetch fee summary** — `POST /v1/forex/summary/fee` — returns `summary.feeDetails`, `summary.tcs`, `summary.gst`, `summary.total`, `summary.lrs`. Pass the same `product.promocodeId` and `summary.feeWaiver` flag you intend to use. 3. **Submit this request** — populate `walletAmount` from step 1 and `summary` from step 2. **Do not independently compute any fee, tax, or rate field.** ### summary Object — What to Pass | Field | Source | Notes | |-------|--------|-------| | `feeDetails` | Fee summary API | **Preferred.** Each key creates a separate ledger entry | | `tcs` | Fee summary API | Pass here **and** in `walletAmount[0].tcs` | | `conversionGst` | Conversion rate API | Triggers a separate branch debit for GST | | `valueOfSupply` | Conversion rate API | Required when `conversionGst > 0` | | `total` | Fee summary API | Grand total the customer pays | | `gst` | Fee summary API | GST on product fees (not conversion) | | `feeWaiver` | Operator decision | Set before calling fee summary API | | `fees` | **Deprecated** | Use `feeDetails` map instead | ### walletAmount Array — What to Pass One entry per currency wallet being loaded. Populate from the conversion rate API response. - `tcs` in `walletAmount[0]` must equal `summary.tcs` (duplication required for ledger routing) - `fees`, `gst` at wallet level echo from conversion/fee API — do not compute independently - `discountRate`, `discountAmount` echo from conversion rate API — do not alter ### Fee Waiver Set `summary.feeWaiver = ALLOWED` when the customer qualifies for a fee waiver. You must upload the waiver approval document and pass its reference in `summary.feeWaiverApproval`. Re-call the fee summary API with `feeWaiver: ALLOWED` to get the zero-fee breakdown before submitting. TCS and `conversionGst` are **never waived** — they are regulatory charges. ### Promo Codes If a promo code is active for this product, pass `product.promocodeId` (the internal promo code ID provided by M2P, **not** a customer-facing promo string). Pass the same `promocodeId` when calling the fee summary API to receive the promotional fee schedule. The promo code affects product-level fees (registration, load fee) only — TCS and conversionGst are unaffected. **Do not pass `promocodeId` in reload requests** — the platform reads it automatically from the card's original issuance record. ### Compliance Documents - **Passport**: Mandatory for all forex loads - **Visa**: Required for travel-related loads - **Air Ticket**: Required for travel loads - **Purpose Proof**: Required for educational/medical purpose - **A2 Form**: RBI declaration form - **Fee Waiver Approval**: Required if `feeWaiver = ALLOWED` ### Key Fields - `kitNo`: Card kit number - `wallet.accountId`: Target currency wallet account ID - `amount`: Load amount in the foreign currency (e.g., 500 for $500 USD) - `hierarchyId`: Branch/corporate hierarchy ID processing the load - `transactionType`: Always `CREDIT` for this endpoint
Debit & Close Forex Card POST
Debits the **entire balance** from a forex card wallet and closes the account. This is a terminal operation — the wallet cannot be reused after closure. ### When to Use - Trip is complete and customer wants to encash all remaining forex - Card surrender / account closure process - Expired card balance pullback ### Behavior 1. The full balance is debited from the specified wallet 2. The wallet status is changed to CLOSED 3. Funds are credited to the customer's bank account (via funding source details) 4. If this is the last active wallet, the card may also be closed