Skip to main content

​
Overview

A digital Wallet (e-wallet) allows users to store value or link funding sources and authorize payments using the stored wallet or linked instruments. In many markets, digital wallets are a preferred method due to convenience, familiarity, and strong authentication. By offering digital wallet payments via Monxa, merchants can:
  • Provide a frictionless checkout experience
  • Tap into local wallet popularity in Asia
  • Leverage Monxa’s settlement, reconciliation, and refund capabilities in one unified system

1. Create a Charge

Initiate the payment by creating a charge in your system with the transaction details.

2. Redirect Customer to e-Wallet

Use the return_url from Monxa to send the customer to their e-wallet app or hosted page.

3. Customer Authorizes Payment

The customer confirms the transaction by entering their PIN/OTP or using biometric authentication in their e-wallet.

4. Handle Webhooks

Once the e-wallet provider processes the payment, Monxa sends a webhook notification to update your system with the final status.

​
Supported Channels

ChannelCodeCurrencyRefundSettlementMin AmountMax Amount
DANAwallet_danaIDRFull, PartialT+210020,000,000
OVOwallet_ovoIDRNot SupportedT+210020,000,000
ShopeePaywallet_shopeeIDRFullT+210020,000,000
LinkAjawallet_linkajaIDRFullT+210020,000,000

​
Payment Flow

Generally, wallet payments follow two types of flows: redirection (jump app) or push notification. The diagram below illustrates a simplified architecture of how Monxa, the merchant, and the wallet provider interact.

​
Step 1: Create a Charge

Endpoint: POST v1/charges
curl https://api.monxa.io/v1/charges \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chg-12345-unique-key" \
  -d '{
    "amount": 150000,
    "currency": "IDR",
    "channel_code": "dana",
	"channel_properties": {
		"return_url": ""
	}
    "reference_id": "INV-240001",
    "metadata": { "field_1": "A1234", field_2: "[email protected]" }
  }'

{
  "id": "chg_01JAB1XYN01P3",
  "reference_id": "INV-240001",
  "amount": 150000,
  "currency": "IDR",
  "status": "pending",
  "channel_code": "dana",
  "actions": {
    "type": "REDIRECT_CUSTOMER",
   	"redirect_url": "",
    "expires_at": "2025-10-07T09:15:00Z"
  },
  "created_at": "2025-10-07T09:10:00Z"
}

​
Step 2: Redirect Customer to Wallet

After creating the payment request, use the response data to generate a QR code and present it to the user.

​
Step 3: Customer Authorizes Payment

After creating the payment request, use the response data to generate a QR code and present it to the user.

​
Step 4: Handle Webhooks & Update Payment Status

Monxa will send an asynchronous webhook to your configured endpoint: Handling Logic (Merchant Side)
  • On SUCCESS: mark order paid, fulfill goods
  • On FAILED or CANCELLED: notify user, optionally prompt fallback
  • On PENDING: you may poll or await final callback
Tip: For general information on webhooks and best practices for handling them, refer to the Webhook Guide page.
ParameterDescriptionExample Value
payment_idUnique identifier of the payment.pay_1234567890
payment_request_idUnique identifier of the payment request.req_0987654321
phoneBuyer’s phone number.+6591234567
amountAmount related to the payment.100.00
currencyCurrency of the payment.SGD
statusPayment status (completed / failed).completed
reference_numberCustom reference number mapped during payment request creation.ORDER12345
hmacMessage Authentication Code (MAC) of this webhook request (used for validation).a1b2c3d4e5f67890abcdef123456

​
Refunds / Reversal

Refunds for e-wallet payments depend on the capabilities of the wallet provider.
Some wallets support full or partial refunds through Monxa’s API, while others do not allow refunds and require a manual refund process outside the system.
  • Supported wallets → You can request a full or partial refund via Monxa’s /v1/refunds endpoint. The provider will process the reversal and return the funds to the customer’s wallet balance.
  • Unsupported wallets → Refunds are not available through the API. Merchants must perform a manual refund (e.g., bank transfer, store credit, or direct arrangement with the customer).
  • Webhook notifications → For supported wallets, Monxa will notify you of refund status updates via events such as refund.succeeded or refund.failed.
Endpoint: POST v1/refunds
curl https://api.monxa.io/v1/refunds \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ref-12345-unique-key" \
  -d '{
    "charge_id": "chg_01JAB1XYN01P3",
    "currency": "IDR",
    "amount": "50000",
    "reference_id": "INV-240001",
	"description": "",
    "metadata": { "field_1": "A1234", field_2: "[email protected]" }
  }'

{
  "id": "ref_01JAB1XYN01P3",
  "reference_id": "INV-240001",
  "amount": 150000,
  "currency": "IDR",
  "status": "pending",
  "channel_code": "dana",
  "actions": {
    "type": "REDIRECT_CUSTOMER",
   	"redirect_url": "",
    "expires_at": "2025-10-07T09:15:00Z"
  },
  "created_at": "2025-10-07T09:10:00Z"
}
Important: Always check the wallet’s capabilities in Monxa’s dashboard or API documentation. The refund feature may vary by provider and by country.

​
Merchant Best Practices

  • Place e-wallet options prominently in checkout, especially in regions where they are popular
  • Use deep linking / SDK embed flows to minimize context switching
  • Pre-validate wallet availability (region, currency, user status) before initiating the flow
  • Handle PENDING status gracefully (polling, UI feedback)
  • Log analytics around wallet provider, time to approve, dropoffs
  • Provide alternative payment options if e-wallet fails
  • If refund-to-wallet isn’t supported, define clear fallback behavior (e.g. bank refund)
  • Be cautious of transaction limits (some wallets limit per day / per transaction)
  • Test across multiple devices, network conditions, and wallet states (e.g. insufficient balance)