VibeMoney API Documentation

Complete guide to integrate VibeMoney payment simulation and subscription management into your application

🚀 Quick Start

  1. 1 Create an account and generate your API key
  2. 2 Generate signed payment links using the HMAC-SHA256 algorithm
  3. 3 Redirect users to payment pages and collect conversion data

💳 Creating Payment Links

🔐 HMAC-SHA256 Signature

All payment data must be signed using HMAC-SHA256 with your API key for security:

// Data string format (pipe-separated)
const dataToSign = `${userId}|${amount}|${productName}|${orderNumber}`;

// Create HMAC signature
const signature = crypto
    .createHmac('sha256', apiKey)
    .update(dataToSign)
    .digest('hex');

Example: For data "user123|29.99|Premium Plan|ORD-001" with API key "test_key", the signature would be calculated as shown above.

🔗 Payment URL Structure

Payment URLs follow this format:

https://vibemoney.online/payment?
    userId=user123&
    amount=29.99&
    productName=Premium%20Plan&
    orderNumber=ORD-001&
    apiKey=your-api-key&
    signature=a1b2c3d4e5f6...

⚠️ Important: All parameters must be URL-encoded. This is especially important for productName if it contains spaces or special characters.

📋 API Parameters

Parameter Type Required Description Example
userId string Yes Unique buyer identifier user123
amount decimal Yes Payment amount in US dollars 29.99
productName string Yes Product or service name Premium Plan
orderNumber string Yes Unique order number ORD-001
apiKey string Yes Your API key from the dashboard vibe_test_...
signature string Yes HMAC-SHA256 data signature a1b2c3d4...

💻 Code Examples

JavaScript/Node.js

const crypto = require('crypto');

class VibeMoney {
    constructor(apiKey) {
        this.apiKey = apiKey;
        this.baseUrl = 'https://vibemoney.online';
    }

    createPaymentLink(userId, amount, productName, orderNumber) {
        // Create signature
        const dataToSign = `${userId}|${amount}|${productName}|${orderNumber}`;
        const signature = crypto
            .createHmac('sha256', this.apiKey)
            .update(dataToSign)
            .digest('hex');

        // Create URL with parameters
        const params = new URLSearchParams({
            userId,
            amount: amount.toString(),
            productName,
            orderNumber,
            apiKey: this.apiKey,
            signature
        });

        return `${this.baseUrl}/payment?${params.toString()}`;
    }
}

// Usage example:
const vibeMoney = new VibeMoney('your-api-key');
const paymentLink = vibeMoney.createPaymentLink(
    'user123', 
    29.99, 
    'Premium Plan', 
    'ORD-001'
);
console.log(paymentLink);

Python

import hmac
import hashlib
from urllib.parse import urlencode

class VibeMoney:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://vibemoney.online'
    
    def create_payment_link(self, user_id, amount, product_name, order_number):
        # Create signature
        data_to_sign = f"{user_id}|{amount}|{product_name}|{order_number}"
        signature = hmac.new(
            self.api_key.encode('utf-8'),
            data_to_sign.encode('utf-8'),
            hashlib.sha256
        ).hexdigest()
        
        # Create URL with parameters
        params = {
            'userId': user_id,
            'amount': str(amount),
            'productName': product_name,
            'orderNumber': order_number,
            'apiKey': self.api_key,
            'signature': signature
        }
        
        return f"{self.base_url}/payment?{urlencode(params)}"

# Usage example:
vibe_money = VibeMoney('your-api-key')
payment_link = vibe_money.create_payment_link(
    'user123',
    29.99,
    'Premium Plan',
    'ORD-001'
)
print(payment_link)

PHP

apiKey = $apiKey;
    }
    
    public function createPaymentLink($userId, $amount, $productName, $orderNumber) {
        // Create signature
        $dataToSign = "$userId|$amount|$productName|$orderNumber";
        $signature = hash_hmac('sha256', $dataToSign, $this->apiKey);
        
        // Create URL with parameters
        $params = http_build_query([
            'userId' => $userId,
            'amount' => (string)$amount,
            'productName' => $productName,
            'orderNumber' => $orderNumber,
            'apiKey' => $this->apiKey,
            'signature' => $signature
        ]);
        
        return $this->baseUrl . '/payment?' . $params;
    }
}

// Usage example:
$vibeMoney = new VibeMoney('your-api-key');
$paymentLink = $vibeMoney->createPaymentLink(
    'user123',
    29.99,
    'Premium Plan',
    'ORD-001'
);
echo $paymentLink;
?>

🔄 Subscription Management

VibeMoney supports recurring subscription payments with management capabilities.

Creating Subscription Links

Subscription URL Structure:

https://vibemoney.online/subscription?
    signature=abc123...&
    user_id=user123&
    customer_id=customer456&
    amount=29.99&
    product_name=Premium%20Plan&
    order_number=ORD-001&
    period=monthly&
    api_key=your-api-key

HMAC Signature for Subscriptions:

Subscription data must be signed with customerId included:

// Data string format for subscriptions (colon-separated)
const dataToSign = `${userId}:${customerId}:${amount}:${productName}:${orderNumber}:${period}`;

// Create HMAC signature
const signature = crypto
    .createHmac('sha256', apiKey)
    .update(dataToSign)
    .digest('hex');

Subscription Parameters:

Parameter Type Required Description
user_id string Yes Unique user identifier
customer_id string Yes Unique customer identifier for subscription
amount decimal Yes Recurring payment amount
period string Yes monthly, yearly, weekly

Checking Subscription Status

Query subscription information using the API:

// GET request to check subscription status
const response = await fetch('/api/subscription-status', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        customerId: 'customer123',
        apiKey: 'your-api-key'
    })
});

const subscription = await response.json();
console.log(subscription.status); // 'active', 'canceled', 'expired'

Response Example:

{
  "success": true,
  "subscription": {
    "id": "sub_1234567890",
    "customerId": "customer123",
    "status": "active",
    "amount": 29.99,
    "period": "monthly",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "canceledAt": null
  }
}

Subscription Cancellation

Generate secure cancellation links for customers:

Creating Cancel Links:

// Generate cancellation signature
const cancelData = `${customerId}`;
const cancelSignature = crypto
    .createHmac('sha256', apiKey)
    .update(cancelData)
    .digest('hex');

// Create cancellation URL
const cancelUrl = `https://vibemoney.online/cancel-subscription?` +
    `customerId=${customerId}&` +
    `apiKey=${apiKey}&` +
    `signature=${cancelSignature}`;

Cancel URL Structure:

https://vibemoney.online/cancel-subscription?
    customerId=customer123&
    apiKey=your-api-key&
    signature=abc123...

⚠️ Security Note: Cancel links are one-time use and automatically expire after successful cancellation. The signature only includes customerId for security.

Complete JavaScript Example

class VibeMoneySubscriptions {
    constructor(apiKey) {
        this.apiKey = apiKey;
        this.baseUrl = 'https://vibemoney.online';
    }

    // Create subscription link
    createSubscriptionLink(userId, customerId, amount, productName, orderNumber, period) {
        const dataToSign = `${userId}:${customerId}:${amount}:${productName}:${orderNumber}:${period}`;
        const signature = crypto
            .createHmac('sha256', this.apiKey)
            .update(dataToSign)
            .digest('hex');

        const params = new URLSearchParams({
            signature,
            user_id: userId,
            customer_id: customerId,
            amount: amount.toString(),
            product_name: productName,
            order_number: orderNumber,
            period,
            api_key: this.apiKey
        });

        return `${this.baseUrl}/subscription?${params}`;
    }

    // Generate cancel link
    createCancelLink(customerId) {
        const signature = crypto
            .createHmac('sha256', this.apiKey)
            .update(customerId)
            .digest('hex');

        const params = new URLSearchParams({
            customerId,
            apiKey: this.apiKey,
            signature
        });

        return `${this.baseUrl}/cancel-subscription?${params}`;
    }

    // Check subscription status
    async getSubscriptionStatus(customerId) {
        const response = await fetch(`${this.baseUrl}/api/subscription-status`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                customerId,
                apiKey: this.apiKey
            })
        });
        
        return await response.json();
    }
}

// Usage example:
const subscriptions = new VibeMoneySubscriptions('your-api-key');

// Create subscription
const subscriptionLink = subscriptions.createSubscriptionLink(
    'user123',
    'customer456', 
    29.99,
    'Premium Plan',
    'ORD-001',
    'monthly'
);

// Create cancel link
const cancelLink = subscriptions.createCancelLink('customer456');

// Check status
const status = await subscriptions.getSubscriptionStatus('customer456');

🔒 Security Requirements

  • API Key Protection: Store API keys securely and never expose them in client-side code
  • Server-Side Signing: Always create signatures on the server side, never in the browser
  • Parameter Validation: Validate all parameters before creating signatures
  • Unique Order Numbers: Ensure order numbers are unique to prevent duplicate payments
  • HTTPS Only: Always use HTTPS for payment links in production

🔔 Webhook Notifications

VibeMoney automatically sends payment results to your configured callback URL when payments are completed or failed.

Setting up Webhooks

  1. 1. Login to your dashboard
  2. 2. Go to the "API Keys" section
  3. 3. Enter your webhook URL in the "Callback URL" field
  4. 4. Click "Save" to activate webhook delivery

📦 Webhook Payload

Payment Success (payment.succeeded):

{
  "event": "payment.succeeded",
  "paymentId": "abc123...",
  "orderNumber": "ORD-001",
  "productName": "Premium Plan",
  "amount": 29.99,
  "currency": "USD",
  "userId": "user123",
  "status": "completed",
  "completedAt": "2024-01-15T10:30:00.000Z",
  "stripePaymentIntentId": "pi_1234567890"
}

Payment Failure (payment.failed):

{
  "event": "payment.failed",
  "paymentId": "abc123...",
  "orderNumber": "ORD-001",
  "productName": "Premium Plan",
  "amount": 29.99,
  "currency": "USD",
  "userId": "user123",
  "status": "failed",
  "failedAt": "2024-01-15T10:30:00.000Z",
  "stripePaymentIntentId": "pi_1234567890",
  "failureReason": "Your card was declined."
}

Subscription Success (subscription.succeeded):

{
  "event": "subscription.succeeded",
  "subscriptionId": "sub_1234567890",
  "customerId": "customer123",
  "orderNumber": "ORD-001",
  "productName": "Premium Plan",
  "amount": 29.99,
  "currency": "USD",
  "period": "monthly",
  "userId": "user123",
  "status": "active",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "stripeSubscriptionId": "sub_1234567890"
}

Subscription Cancellation (subscription.canceled):

{
  "event": "subscription.canceled",
  "subscriptionId": "sub_1234567890",
  "customerId": "customer123",
  "orderNumber": "ORD-001",
  "productName": "Premium Plan",
  "amount": 29.99,
  "currency": "USD",
  "period": "monthly",
  "userId": "user123",
  "status": "canceled",
  "canceledAt": "2024-01-15T10:45:00.000Z",
  "stripeSubscriptionId": "sub_1234567890"
}

⚡ Best Practices

  • Respond quickly: Return HTTP 200 status within 10 seconds
  • Handle duplicates: Use paymentId to prevent duplicate processing
  • Verify events: Check that the webhook comes from your expected payments
  • Use HTTPS: Webhook URLs must use HTTPS in production

Payment Status Check API

Query the status of existing payments using order number and amount with API key authentication.

API Endpoint

POST https://vibemoney.online/api/check-payment-status

Request Body

{
  "orderNumber": "ORD-12345",      // The unique order number
  "amount": 29.99,                // The payment amount (must match exactly)
  "signature": "hmac-signature"    // HMAC-SHA256 signature
}

Signature Creation

// Data to sign: userId|amount|orderNumber
const dataToSign = `${userId}|${amount}|${orderNumber}`;
const signature = crypto.createHmac('sha256', apiKey).update(dataToSign).digest('hex');

Response (Payment Found)

{
  "success": true,
  "status": "completed",
  "payment": {
    "id": "abc123...",
    "orderNumber": "ORD-12345",
    "productName": "Premium Plan",
    "amount": 29.99,
    "currency": "USD",
    "status": "completed",
    "companyName": "Your Company",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "completedAt": "2024-01-15T10:35:00.000Z"
  }
}

Response (Payment Not Found)

{
  "success": false,
  "status": "not_found",
  "message": "Payment not found with the provided order number and amount"
}

🔒 Security Notes

  • • Signature must be created server-side using your API key
  • • Only payments created by API key owner can be queried
  • • Amount must match exactly (including decimals)
  • • Order numbers are case-sensitive

Need Help?

Ready to start testing payments? Create your account and get your API key.

Questions? Contact us at support@vibemoney.com