VibeMoney API Documentation
Complete guide to integrate VibeMoney payment simulation and subscription management into your application
🚀 Quick Start
- 1 Create an account and generate your API key
- 2 Generate signed payment links using the HMAC-SHA256 algorithm
- 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. Login to your dashboard
- 2. Go to the "API Keys" section
- 3. Enter your webhook URL in the "Callback URL" field
- 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