Withdraw Tokens

Programmatically withdraw tokens from a user’s balance for specific paywall operations.

Tokenized Paywalls Only: This endpoint only works with tokenized paywalls. Learn more about paywall tokenization.

Owner Authorization Required: The API key owner must be the creator of the paywall for which tokens are being withdrawn.

Overview

The Withdraw Tokens API endpoint allows you to programmatically deduct tokens from a user’s balance. This is useful for:

Custom token consumption - Implement your own token-based features
Manual adjustments - Adjust user balances for special cases

API Reference

Endpoint


POST https://onlineapp.pro/api/v1/withdraw-tokens

Authentication

Authenticate your requests by including your API key in the X-Api-Key header.


X-Api-Key: your-api-key

Get your API key

API Key Location

Request Body


{
  "paywall_id": "123",
  "user_id": "user-uuid",
  "tokens": 5,
  "token_type": "standard"
}

Request Parameters

Parameter	Type	Required	Description
`paywall_id`	string	Yes	ID of the paywall
`user_id`	string	Yes	ID of the user whose tokens will be withdrawn
`tokens`	number	Yes	Number of tokens to withdraw (must be > 0)
`token_type`	string	No	Type of tokens to withdraw (default: “standard”)

Success Response

Status: 200 OK


{
  "success": true,
  "remaining": 45
}

Field	Type	Description
`success`	boolean	Indicates successful token withdrawal
`remaining`	number	Number of tokens of the specified type left after withdrawal

Basic Usage

Simple Token Withdrawal


const withdrawTokens = async (paywallId, userId, tokensToWithdraw, tokenType = 'standard') => {
  try {
    const response = await fetch('https://onlineapp.pro/api/v1/withdraw-tokens', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Api-Key': 'your-api-key'
      },
      body: JSON.stringify({
        paywall_id: paywallId,
        user_id: userId,
        tokens: tokensToWithdraw,
        token_type: tokenType
      })
    });
 
    const result = await response.json();
 
    if (!response.ok) {
      throw new Error(result.error || `HTTP ${response.status}`);
    }
 
    return result;
  } catch (error) {
    console.error('Failed to withdraw tokens:', error);
    throw error;
  }
};
 
// Usage
const result = await withdrawTokens('123', 'user-uuid-123', 5, 'standard');
console.log(`Withdrawal successful. Remaining tokens: ${result.remaining}`);

Error Handling

Error Responses

Authentication Errors

Missing API Key (401)


{"error": "API key is required"}

Invalid API Key (401)


{"error": "Invalid API key"}

Inactive API Key (403)


{"error": "API key is inactive"}

Authorization Errors

Not the Owner (403)


{"error": "Unauthorized. You are not the owner of this paywall"}

Validation Errors

Missing Parameters (400)


{"error": "User ID is required"}

Insufficient Tokens (400)


{
  "error": "Insufficient tokens",
  "available": 3,
  "requested": 5
}

Not Found Errors

Paywall Not Found (404)


{"error": "Paywall not found"}

User Balance Not Found (404)


{"error": "No balance found for this user and paywall"}

Comprehensive Error Handler


const handleWithdrawalError = (error, response) => {
  switch (response?.status) {
    case 400:
      if (error.includes('Insufficient tokens')) {
        return {
          type: 'insufficient_balance',
          message: 'Not enough tokens available for withdrawal',
          userMessage: 'Insufficient token balance'
        };
      }
      return {
        type: 'validation_error',
        message: error,
        userMessage: 'Please check your input and try again'
      };
 
    case 401:
      return {
        type: 'authentication_error',
        message: error,
        userMessage: 'Authentication failed. Please check your API key'
      };
 
    case 403:
      return {
        type: 'authorization_error',
        message: error,
        userMessage: 'You do not have permission to perform this action'
      };
 
    case 404:
      return {
        type: 'not_found_error',
        message: error,
        userMessage: 'Paywall or user not found'
      };
 
    default:
      return {
        type: 'unknown_error',
        message: error,
        userMessage: 'An unexpected error occurred. Please try again'
      };
  }
};
 
const safeWithdrawTokens = async (paywallId, userId, tokens, tokenType) => {
  try {
    const result = await withdrawTokens(paywallId, userId, tokens, tokenType);
    return { success: true, data: result };
  } catch (error) {
    const errorInfo = handleWithdrawalError(error.message, error.response);
    console.error('Token withdrawal error:', errorInfo);
 
    return {
      success: false,
      error: errorInfo.type,
      message: errorInfo.userMessage,
      details: errorInfo.message
    };
  }
};

Security Guidelines

1. Secure API Key Management


// Good: Use environment variables
const apiKey = process.env.PAYWALL_API_KEY;
 
// Bad: Hardcode API keys
// const apiKey = 'your-api-key-here'; // Never do this!

Next Steps

Paywall Tokenization Get User Data Modify Balances (Test)