Skip to main content

Getting Started with VesuvioPay SDK

Welcome to VesuvioPay SDK! This guide will help you integrate our payment and e-commerce platform into your application.

What is VesuvioPay SDK?​

VesuvioPay SDK provides a comprehensive API for:

  • Product Management: Sync products from external platforms (Shopify, WooCommerce, etc.)
  • Customer Management: Access and manage customer data
  • Cart Operations: Build shopping cart experiences
  • Order Processing: Create and manage orders
  • Webhooks: Receive real-time notifications for events

Prerequisites​

Before you begin, you'll need:

  1. A VesuvioPay account
  2. Access to your VesuvioPay dashboard
  3. API credentials (API key pair)
  4. Basic understanding of REST APIs and HTTP

Quick Start​

Step 1: Obtain Your API Keys​

  1. Log in to your VesuvioPay Dashboard
  2. Navigate to Settings > API Keys
  3. Generate a new API key pair
  4. You'll receive:
    • Publishable Key (starts with pk_): Safe for client-side use
    • Secret Key (starts with sk_): Keep secure, server-side only
Keep Your Secret Key Secure

Never expose your secret key in client-side code, public repositories, or frontend applications.

Step 2: Make Your First API Call​

Here's a simple example to retrieve your store's checkout settings:

curl https://api.vesuviopay.com/api/v1/sdk/store/{storeId}/checkout-settings \
  -H "X-API-Key: pk_test_your_publishable_key_here"
// JavaScript/TypeScript Example
const response = await fetch(
  `https://api.vesuviopay.com/api/v1/sdk/store/${storeId}/checkout-settings`,
  {
    headers: {
      'X-API-Key': 'pk_test_your_publishable_key_here',
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();
console.log(data);
// C# Example
using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "pk_test_your_publishable_key_here");

var response = await client.GetAsync(
    $"https://api.vesuviopay.com/api/v1/sdk/store/{storeId}/checkout-settings"
);

var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);

Step 3: Test Mode vs Production​

VesuvioPay provides separate API keys for testing and production:

  • Test Keys: pk_test_... and sk_test_...
  • Production Keys: pk_live_... and sk_live_...

Always use test keys during development and switch to production keys when you're ready to go live.

Base URL​

All API requests should be made to:

https://api.vesuviopay.com

API Version: All endpoints are versioned. Current version is v1.

Authentication​

VesuvioPay uses API keys for authentication. Include your API key in the X-API-Key header:

X-API-Key: your_api_key_here

Some cart operations also require a JWT token for customer authentication. Learn more in the Authentication guide.

Response Format​

All API responses are returned in JSON format:

Success Response (200 OK):

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    // Response data here
  }
}

Error Response (4xx or 5xx):

{
  "success": false,
  "message": "Error description",
  "errorCode": "ERROR_CODE",
  "errors": [
    {
      "field": "fieldName",
      "message": "Validation error message"
    }
  ]
}

Next Steps​

Now that you've made your first API call, explore these guides:

  1. Authentication - Learn about API keys and JWT authentication
  2. Product Sync Guide - Sync your product catalog
  3. Cart Integration - Build cart functionality
  4. Webhooks - Receive real-time event notifications
  5. Error Handling - Handle errors gracefully

Need Help?​

SDK Libraries​

Coming Soon

Official SDK libraries for JavaScript/TypeScript, Python, and .NET are in development. For now, you can use any HTTP client to make API requests.