API Guidance
Onboard Wallet APIs
If you wish to use the Wallet function, we recommend performing testing on the provided TEST platform. Your Moloco representative will create a TEST platform during your initial onboarding.
To use the Wallet API, a prepaid advertising expense charging service with a payment module must be implemented, Moloco does not provide this service. The payment 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:
- Set the fixed value for the Credits you intend to allocate.
- Prepare a list of IDs (
ad_account_id
) for the Ad accounts that will participate in the advertising business. - Use the QueryWallets API to gather all Ad account IDs and their corresponding Wallet IDs (
wallet_id
) on the platform. - Sequentially process the Ad account IDs list obtained in the previous step 2
- Use the Ad account ID and the corresponding Wallet ID to call the TopUpWallet API.
- Set the type in the top_up object to
CREDITS
. - For the
Amount
object, Set thecurrency
value likeUSD
and set theamount
to the micro-unit of the amount specified in Step 1. For example, for 1 USD, the micro-unit would be1000000
.
- Set the type in the top_up object to
- Use the Ad account ID and the corresponding Wallet ID to call the TopUpWallet API.
- For verification, after completing the above steps, iterate through the Ad account IDs from Step 2 again.
- Use the Ad account ID to call the ListWallets API.
- 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.
Authentication
The Wallet functions are part of the Management API suite which requires an API Key for authentication. The Management API Key should be used in the API Header Authentication when making Management API calls.
Please refer to the API Key and SSO credential management page for detailed guidance on creating and using the an API Key.
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.
TopUp
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
.
Example TopUp request body
{
"top_up": {
"type": "CREDITS",
"amount": {
"currency": "USD",
"amount_micro": "10000000"
}
},
"comment": "comment for credits top-up"
}
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.comment
: User supplied comment, which will be saved in the wallet history.
Example Withdraw request body
{
"withdraw": {
"type": "CREDITS",
"amount": {
"currency": "USD",
"amount_micro": "100000000"
}
},
"comment": "comment for credits withdrawal"
}
If the API call is successful, the amount specified in the Wallet account associated with the advertising account will be withdrawn (deducted).
If a user attempts to withdraw an amount greater than the available balance, an error message will be displayed with the current remaining balance and relevant information.
Example “Insufficient Wallet Balance” error message
{
"code": 9,
"message": "the account CREDITS does not have enough balance to withdraw after deducting real-time ad spending [id:iRNTmO12zemLsKeX]",
"details": [
{
"@type": "type.googleapis.com/api.adcloud.common.ErrorInfo",
"category": "INSUFFICIENT_WALLET_BALANCE",
"metadata": {
"account_type": "CREDITS",
"real_time_ad_spending": 0,
"remaining_balance": 20000000,
"withdraw_amount": 2500000000
}
}
]
}
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.
Wallet History
The WalletHistory API provides a complete history of all changes made to a wallet. comment
and changed_by
fields are displayed from previous TopUp
or WithdrawWallet
requests within the Wallet History response.
Example Wallet History response:
{
"type": "FUNDED",
"budget_change": {
"credits": {
"currency": "USD",
"amount_micro": "200000000"
},
"prepaid": {
"currency": "USD",
"amount_micro": "0"
},
"total": {
"currency": "USD",
"amount_micro": "200000000"
}
},
"balance": {
"credits": {
"currency": "USD",
"amount_micro": "500000000"
},
"prepaid": {
"currency": "USD",
"amount_micro": "2000000000"
},
"total": {
"currency": "USD",
"amount_micro": "2500000000"
}
},
"updated_at": "2024-09-09T05:01:29.167336Z",
"metadata": {
"comment": "comment for TopUp transaction"
},
"changed_by": {
"id": "g7i28ribRX77nHqZoKf0z",
"name": "user_name",
"email": "[email protected]",
"role": "PLATFORM_OWNER"
}
},...
Updated 27 days ago