m2pfintech
API LibraryTransaction

Debit & Close Forex Card

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
POST
/v1/forex/card-holder-loads/debit-closure

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

hierarchyId*string

Required. Branch/corporate hierarchy ID

Length1 <= length
kitNo*string

Required. Card kit number associated with the particular card/product

Length1 <= length
entityId?string

Unique entity identifier for the transaction associated with the customer

mobile?

Customer's mobile number

name?string

Full name of the customer

hashedCard?string

Encrypted Card Number of the customer

customerId?string

Unique customer identifier

cardTypeEnum?string

Type of card issued; Single for single-user, Bulk for bulk issuance

Value in"Single" | "Bulk"
amount*number

Transaction amount in the wallet currency

Range0 <= value
description?string

Description or remarks for the transaction

transactionType*string

Required. CREDIT for loading, DEBIT for withdrawal

Value in"CREDIT" | "DEBIT"
debitTransactionType?string

Indicates partial or full debit transaction

Value in"PARTIAL_DEBIT" | "FULL_DEBIT" | "FULL_DEBIT_WITH_CLOSURE"
product*

Product details associated with the transaction

wallet*

Wallet details used for the transaction

trip?

Trip details (required for CREDIT operations)

funding?

Funding source details

walletAmount?

List of wallet amounts and conversion details (for multi-wallet operations)

summary?

Summary of transaction including fees, GST, TCS, etc.

feeWaiverApprovalReason?string

Reason for fee waiver approval, if any

declarations?

Declarations such as FATCA, ITR, T&C, LRS

branchCode?string

Branch code or hierarchy ID where the transaction occurred

tellerId?string

Teller ID who processed the transaction

rrn?string

Retrieval Reference Number for the transaction

channel?string

Indicates which channel this transaction is initiated from

isBranch?boolean

Indicates if transaction is initiated from a branch

makerChecker?boolean

Indicates if maker-checker workflow is enabled for this transaction

loanDetails?

Loan details if applicable; mandatory if purpose of travel is EDUCATIONAL_LOAN_LETTER

customAttributes?

Custom attributes for additional data

bulkUpload?

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.

id?string
issuerTenant?string
status?string
Value in"SUCCESS" | "FAILED" | "CREATED"
tenant?string
txnStatus?string
Value in"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-closure" \  -H "X-TENANT-ID: ACME_CORP" \  -H "Content-Type: application/json" \  -d '{    "hierarchyId": "90009",    "kitNo": "320000541",    "entityId": "476843769320000541160925",    "mobile": {      "value": "9876543210",      "countryCode": 91    },    "transactionType": "DEBIT",    "debitTransactionType": "FULL_DEBIT_WITH_CLOSURE",    "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": "Invalid account for given card",
  "status": 409,
  "detail": "Invalid account for given card",
  "message": "error.business",
  "businessCode": "PP_CORP_045"
}

Debit Forex Card (Partial Withdrawal) POST

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.

Download Statement as PDF POST

Generates and returns a transaction statement as a downloadable PDF. Use this endpoint when you need to display or save the statement in your application rather than emailing it to the cardholder. ### How It Works 1. Provide the same request parameters as the email statement API 2. The system generates the PDF statement synchronously 3. The PDF content is returned as a base64-encoded string in the response 4. Decode the base64 string to get the PDF file ### Key Business Rules - Same date range restrictions as the email statement API (max 1 year) - The response contains the PDF as a base64-encoded string - Large date ranges with many transactions may take longer to process - Consider implementing pagination for transaction history if you need to display transactions in your UI (use the Transaction History API instead)