Disclaimer

Depending on the country, receiving advertising fees from advertisers for charging the Wallet may be subject to value-added tax or other taxes. This aspect needs to be verified and handled by the retail platform. Moloco does not interfere with any tax-related processes required for using the Wallet function.

Introduction

The Wallet function in Moloco Commerce Media provides various features, such as prepaying advertising expenses, granting credits, and viewing advertising expenditure details for each advertising account (Ad account). This enables retail platform users to use a prepaid or the traditional post-payment method for advertising expenses. It also allows providing credits for advertising expenses based on promotions and events.

Concepts

Below are the key concepts and terms necessary to use the Wallet function:

Platform

The platform represents your marketplace using Moloco Commerce Media’s Sponsored Ads. Moloco will provide you with a Platform ID when you onboard an account with us. This ID is required to make API requests to Moloco Commerce Media APIs.

Ad Account

Advertisers who wish to use platform advertising services are provided with an ad account. For more information on ad accounts, please see 2. Understanding the Components.

Wallet

The Wallet is a virtual wallet that holds the advertising expenses for Moloco Commerce Media. Each Ad account is automatically assigned one Wallet. A Wallet has two accounts, and they can be charged, held, and used separately, depending on their purposes:

• Prepaid: This balanced account is for ad budget funds, excluding taxes advertisers procure to run their campaigns.
• Credits: This balanced account is for any funds your marketplace offers your advertisers for purposes including but not limited to promotional events, supporting their ad business growth, and discretionary compensations.

API Usage

Authentication

The Wallet function is part of the Management API. Therefore, you can acquire a JWT token using the CreateToken API responsible for Management API authentication. Put this token in the API Header Authentication as Bearer to make the API call.

Please refer to the Moloco Widgetized Campaign Manager Guide and API Guide for more detailed guidance on using CreateToken API.

Query and List Wallet

Use the QueryWallets API to see the mapping information between Ad accounts and Wallet IDs within the platform.

To check the current status of a specific Wallet, use the ListWallets API. To call the ListWallets API, you need the following information:

• platform_id: The ID of the platform used in MCM.
• ad_account_id: The ID of the target Ad account.

Top Up

Use the TopUp API to charge the Prepaid and Credits accounts of the Wallet.

For Prepaid, you can implement the following charging method:

• Implement an advertising expense charging service with a payment module for advertisers.
• When advertisers pay a certain amount for this service, calculate the amount excluding value-added tax.
• Call the MCM TopUp API based on the advertiser's Ad account information and the calculated amount (excluding value-added tax). In this case, set the type in the accounts object to PRE_PAID.

For Credits, you can charge as follows:

• Call the MCM TopUp API with the advertising account information and the amount you want to grant as credit. Set the type in the accounts object to CREDITS.

Withdraw

Moloco does not process refunds. The platform owner must handle actual refunds or withdrawals. However, Moloco provides APIs that allow you to withdraw (deduct) the amount stored in the Wallet. To withdraw the amount charged to the Wallet, you can use the WithdrawWallet API.

For this API call, you will need the following information:

• platform_id: The ID of the platform used in MCM.
• ad_account_id: The ID of the target Ad account.
• wallet_id: The ID of the Wallet you want to withdraw the amount from.
• request_id: To prevent repeated withdrawals due to repetitive API calls, a request_id is required. The withdrawal will only be processed once for requests with the same request_id.
• amount: An object for the withdrawal request, which includes the Wallet account type (CREDITS, PRE_PAID) and the amount of information (currency and amount) to be withdrawn.

If the API call is successful, the amount specified in the Wallet account associated with the advertising account will be withdrawn (deducted).

By default, only PRE_PAID account balances can be withdrawn (deducted) if your request to withdraw is larger than the balance in the PRE_PAID account, an error will be returned. If you would like to change this setting, please contact your Moloco representative.

To process refunds:

• To accommodate for late attribution, cases that would cause additional spending on wallet accounts, set the advertising account you want to refund to an inactive state for 24 hours.
• After waiting 24 hours, call the WithdrawWallet API with the advertising account, Wallet IDs, and the amount information.
• Once you receive a successful response, proceed with the refund process for that advertising account on the platform.

QueryWalletAccountHistory

QueryWalletAccountHistory API allows you to view the activity history of wallets to review transactions. You can see the ad accounts' daily expenses (spent), the amount you've added (top-up), and the amount you've taken out (withdrawal).

Types of Transactions are:

• Spent: This shows each platform's daily spending settled at 2 PM
  • Updated based on our daily report pipeline.
  • Any remaining Credits at the time of settlement are the first to be spent.
• Funded: This shows the history of the balance you've added to the account through the TopUp API.
• Refunded: This shows the history of the balance you've taken out of the account through the Withdraw API. Note that you can only do this from a Prepaid account.

Please refer to the link below for detailed API specs: Moloco Commerce Media API Reference - Wallet.

Credits and Prepaid Accounts

When deducting advertising expenses during ad serving, the deduction will start from the Credits account before the Prepaid account. The deduction will be made from the Prepaid account if no funds are in the Credits account.

For example, with $1,000 in Prepaid and $1,000 in Credits, if a deduction of $1,500 occurs during ad serving, the $1,000 in Credits will be used first. Then, $500 will be deducted from the Prepaid account, resulting in a total balance of $500 in Prepaid and $0 in Credits.

For platforms using the Wallet function, if the remaining balance in an advertising account's Wallet is less than a certain amount (BalanceLimit) (the total balance of Prepaid and Credits in the Wallet < BalanceLimit), the advertising account will be automatically deactivated. When the advertising account is deactivated, all campaigns under that account will be suspended, and ads will not be served. If you do not wish to use automatic deactivation, please contact your Moloco representative.

Platforms can also opt-in to set a low wallet balance threshold to send notifications for low-balance ad accounts. Unlike BalanceLimit, ad accounts are not deactivated if their remaining balance is less than the low wallet balance threshold. Instead, these ad accounts will receive warning notifications stating their current low balances. This value is also configurable. Please contact your Moloco representative if you want to use this notification service.

If an advertising account is deactivated due to insufficient balance, even if the Wallet is charged to an amount exceeding the BalanceLimit through the TopUp API, the advertising account will not automatically activate. The activation of the advertising account needs to be done separately by the platform owner.

For example, say the balance limit is set to $2,000, the total balance in the Wallet is $1,900, and the advertising account is deactivated. Even if $10,000 is charged through the TopUp API, resulting in a total balance of $11,900, the advertising account will not automatically activate.

Define Your Policies

Due to the above characteristics, several policy decisions are required to use the Wallet function.

• Setting the BalanceLimit amount.
• Deciding whether to automatically deactivate advertising accounts when the Wallet balance is insufficient (ad account auto-deactivate).
• Deciding whether to use low balance warning notifications for advertising accounts when the Wallet balance is lower than the low wallet balance threshold.
• Determining the timing and method of activating advertising accounts when charging the Wallet (ad account activate).
• Establishing the refund process for the Wallet PRE_PAID account.

Once these decisions are made, please share the details with your Moloco representative.

Onboard Wallet APIs

If you wish to use the Wallet function, we recommend you perform testing first on the provided TEST platform. Please contact your Moloco representative for more information. To use the Wallet API, a prepaid advertising expense charging service with a payment module must be implemented on the platform. This service should include at least the following elements:

• Query: Advertisers should be able to check the current balance of each account (Ad account) and their linked Wallet.
• TopUp: The service should have a form to input the amount charged.
• Payment: The service should be able to handle payment, either by adding value-added tax to the charged amount or processing the payment as is (e.g., card payment or bank transfer). A payment module is required for this.
• Payment Confirmation and TopUp API Call: After payment confirmation, the service should call the MCM TopUp API to charge the PRE_PAID account with a limited amount excluding value-added tax.

Once the above requirements are implemented and tested, you can perform the onboarding and initial Credit-granting tasks for the Wallet API with the following steps:

1. Set the fixed value for the Credits you intend to allocate.
2. Prepare a list of IDs (ad_account_id) for the Ad accounts that will participate in the advertising business.
3. Use the QueryWallets API to gather all Ad account IDs and their corresponding Wallet IDs (wallet_id) on the platform.
4. Sequentially process the Ad account IDs list obtained in the previous step 2
   1. Use the Ad account ID and the corresponding Wallet ID to call the TopUpWallet API.
      1. Set the type in the top_up object to CREDITS.
      2. For the Amount object, Set the currency value like USD and set the amount to the micro-unit of the amount specified in Step 1. For example, for 1 USD, the micro-unit would be 1000000.
5. For verification, after completing the above steps, iterate through the Ad account IDs from Step 2 again.
   1. Use the Ad account ID to call the ListWallets API.
   2. Check the balance in the accounts object for the CREDITS type in the response to verify that the amount specified in step a is set correctly in micro units.

Frequently Asked Questions

Q. What's the difference between the balance shown in Query/List Wallets and the spending history in QueryWalletAccountHistory?

For Query/List Wallets, the balance displayed is a rough approximation to give you a real-time snapshot of your current spending status. This number may be inaccurate and could vary from the final settled amount.

For QueryWalletAccountHistory, The spending history of the wallet provides a comprehensive record of the finalized details for each ad account. History is updated daily at 2 p.m. according to the platform's time zone. If an ad account has leftover credits, they will be used first when the daily update happens.

Here are example scenarios of topping up the credits.

A wallet or advertising account has run out of credits and is currently spending (-$100) from the prepaid account. If you then use the TopUp API to add Credits ($200) to the wallet/ad account before the daily settlement at 2 pm, those newly added credits will be used first because the system prioritizes deducting credits from the Wallet over prepaid funds. This action could alter the balance shown in Query/List Wallets. The actual imp/click attribution and spending are settled daily at 2 pm according to the platform’s timezone. Therefore, the amount shown after settlement may slightly differ from what was displayed earlier.