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:

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.

Authentication

The Wallet functions are part of the Management API suite which requires a Java Web Token (JWT) for authentication. The token can be generated by using the CreateToken API. This token should be used in the API Header Authentication as "Bearer" when making Management API calls.

Please refer to the Management API Usage and CreateToken API pages for detailed guidance on creating and using the JWT.

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"
    }
},...