Wallets

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

🇮🇩 Indonesia
🇹🇭 Thailand

Channel	Code	Currency	Refund	Settlement	Min Amount	Max Amount
DANA	`wallet_dana`	IDR	Full, Partial	T+2	100	20,000,000
OVO	`wallet_ovo`	IDR	Not Supported	T+2	100	20,000,000
ShopeePay	`wallet_shopee`	IDR	Full	T+2	100	20,000,000
LinkAja	`wallet_linkaja`	IDR	Full	T+2	100	20,000,000

Channel	Code	Currency	Refund	Settlement	Min Amount	Max Amount
Alipay	`wallet_ali`	THB	Not supported	T+2	1	50,000
WeChat Pay	`wallet_wechat`	THB	Not supported	T+2	1	70,000
TrueMoney	`wallet_truemoney`	THB	Not supported	T+2	1	50,000
LINE Pay	`wallet_line`	THB	3-5 business days	T+2	1	50,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.

Redirection Flow
Push Notification Flow

Step 1: Create a Charge

Endpoint: POST v1/charges

Request Example : Charge‑only (DANA)

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: "user@example.com" }
  }'

Response Example

{
  "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.

Webhook Parameters

Parameter	Description	Example Value
`payment_id`	Unique identifier of the payment.	`pay_1234567890`
`payment_request_id`	Unique identifier of the payment request.	`req_0987654321`
`phone`	Buyer’s phone number.	`+6591234567`
`amount`	Amount related to the payment.	`100.00`
`currency`	Currency of the payment.	`SGD`
`status`	Payment status (`completed` / `failed`).	`completed`
`reference_number`	Custom reference number mapped during payment request creation.	`ORDER12345`
`hmac`	Message Authentication Code (MAC) of this webhook request (used for validation).	`a1b2c3d4e5f67890abcdef123456`

Sample Webhook (charge.succeeded)

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

Refund Request Example

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: "user@example.com" }
  }'

Response Example (refund.succeeded)

{
  "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)

INTRODUCTION

ACCEPT PAYMENTS

PAYOUTS

REFERENCES

Overview

1. Create a Charge

2. Redirect Customer to e-Wallet

3. Customer Authorizes Payment

4. Handle Webhooks

Supported Channels

Payment Flow

Step 1: Create a Charge

Step 2: Redirect Customer to Wallet

Step 3: Customer Authorizes Payment

Step 4: Handle Webhooks & Update Payment Status

Refunds / Reversal

Merchant Best Practices

​Overview

1. Create a Charge

2. Redirect Customer to e-Wallet

3. Customer Authorizes Payment

4. Handle Webhooks

​Supported Channels

​Payment Flow

​Step 1: Create a Charge

​Step 2: Redirect Customer to Wallet

​Step 3: Customer Authorizes Payment

​Step 4: Handle Webhooks & Update Payment Status

​Refunds / Reversal

​Merchant Best Practices

Overview

Supported Channels

Payment Flow

Step 1: Create a Charge

Step 2: Redirect Customer to Wallet

Step 3: Customer Authorizes Payment

Step 4: Handle Webhooks & Update Payment Status

Refunds / Reversal

Merchant Best Practices