Integration Guide

Getting Started

This integration guide will walk you through the process of integrating VTransaction Expert's payment processing services into your website or application. We offer multiple integration options to fit your specific needs and technical capabilities.

Integration Methods

VTransaction Expert provides the following integration methods:

• Hosted Checkout - Redirect customers to our secure payment page (easiest implementation)
• Direct API Integration - Connect directly to our payment API for complete customization
• iFrame Embedded - Embed our payment form within your website
• Mobile SDK - Native integration for iOS and Android applications
• Platform Plugins - Pre-built integrations for popular e-commerce platforms

Requirements

The basic requirements for integrating with VTransaction Expert include:

• A VTransaction Expert merchant account
• API keys (available in your Merchant Center dashboard)
• SSL/TLS encryption on your website (HTTPS)
• Basic understanding of web development (varies by integration method)

Account Setup

Before you can begin integration, you need to properly set up your VTransaction Expert account and obtain your API credentials.

Obtaining API Keys

Follow these steps to obtain your API keys:

1. Log in to your VTransaction Expert Merchant Center
2. Navigate to Settings > Developer > API Keys
3. Click Generate New API Key if you don't already have one
4. Make sure to securely store both your test and live API keys

Setting Up Webhook Endpoints

Webhooks allow your application to receive real-time notifications about events in your account. To set up webhook endpoints:

1. In your Merchant Center, go to Settings > Developer > Webhooks
2. Click Add Endpoint
3. Enter the URL where you want to receive webhook events
4. Select the events you want to subscribe to (e.g., payment.succeeded, payment.failed)
5. Click Create Endpoint

Configuring Your Account Settings

Before going live, make sure to configure these important account settings:

• Business Information - Complete your business profile with accurate information
• Payment Methods - Enable the payment methods you want to accept
• Fraud Prevention - Configure fraud prevention settings
• Email Notifications - Set up email templates and notifications
• Statement Descriptor - Configure how your business name appears on customer credit card statements

Hosted Checkout

The Hosted Checkout integration is the easiest way to start accepting payments with VTransaction Expert. With this method, customers are redirected to our secure payment page to complete their payment and then returned to your website.

Benefits of Hosted Checkout

• Simplest integration method with minimal coding required
• No PCI compliance concerns as sensitive payment data is handled on our secure servers
• Fully responsive design that works across all devices
• Customizable appearance to match your brand
• Support for all payment methods available in your account

Integration Steps

1. Create a payment session

   First, create a payment session with the transaction details:

   // Server-side code (Node.js example) const VTransaction = require('@vtransactionexpert/vtransaction-js'); const vtransaction = new VTransaction('sk_test_51HG8K3JXhVORy8xG4tiQ2KovA98Xbdg'); async function createCheckoutSession(req, res) { try { const session = await vtransaction.checkout.sessions.create({ payment_method_types: ['card'], line_items: [ { name: 'Product Name', description: 'Product Description', amount: 2000, // $20.00 currency: 'usd', quantity: 1 } ], success_url: 'https://yourwebsite.com/success?session_id={CHECKOUT_SESSION_ID}', cancel_url: 'https://yourwebsite.com/cancel' }); res.json({ sessionId: session.id }); } catch (error) { res.status(500).json({ error: error.message }); } }

2. Redirect to checkout

   Next, redirect your customer to the checkout page using the session ID:

   // Client-side code function redirectToCheckout(sessionId) { window.location.href = `https://checkout.vtransactionexpert.com/v1/checkout/${sessionId}`; } // When customer clicks "Pay" button document.getElementById('payButton').addEventListener('click', async () => { const response = await fetch('/create-checkout-session', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ // Order details }) }); const { sessionId } = await response.json(); redirectToCheckout(sessionId); });

3. Handle completion

   After the payment is completed, the customer will be redirected to your success_url or cancel_url, depending on the outcome. You can verify the payment status on your success page:

   // Server-side code async function handleSuccess(req, res) { const sessionId = req.query.session_id; try { const session = await vtransaction.checkout.sessions.retrieve(sessionId); if (session.payment_status === 'paid') { // Payment successful, fulfill the order // ... res.render('success', { orderDetails: session }); } else { // Payment not completed res.redirect('/payment-error'); } } catch (error) { res.status(500).render('error', { error: error.message }); } }

Customizing the Checkout Page

You can customize the appearance of the hosted checkout page to match your brand:

1. In your Merchant Center, go to Settings > Branding
2. Upload your logo, set brand colors, and customize the page layout
3. Preview the changes and save when you're satisfied

You can also customize the checkout programmatically when creating a session:

Direct API Integration

The Direct API integration provides the most flexibility and customization options for processing payments. With this method, you build your own payment form and connect directly to our API.

Benefits of Direct API Integration

• Complete control over the checkout experience
• Seamless integration with your existing systems
• Access to all API features and capabilities
• No redirects required

Basic API Integration Flow

1. Create a payment form

   Create a secure form on your website to collect payment information:

   Card Number

   Expiration Date

   CVC

   Cardholder Name

   Pay $20.00

2. Collect and tokenize card data

   To reduce PCI scope, collect and tokenize the card data before it reaches your server:

   // Client-side JavaScript document.getElementById('payment-form').addEventListener('submit', async function(event) { event.preventDefault(); const cardData = { number: document.getElementById('card-number').value, exp_month: document.getElementById('card-expiry').value.split(' / ')[0], exp_year: document.getElementById('card-expiry').value.split(' / ')[1], cvc: document.getElementById('card-cvc').value, name: document.getElementById('card-name').value }; try { // Create a payment method token using the frontend SDK const response = await vtransactionClient.paymentMethods.create({ type: 'card', card: cardData }); const paymentMethodId = response.id; // Pass the payment method ID to your server processPayment(paymentMethodId); } catch (error) { // Handle validation errors displayError(error.message); } }); function processPayment(paymentMethodId) { // Send to your server for processing fetch('/process-payment', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ payment_method_id: paymentMethodId, amount: 2000, // $20.00 currency: 'usd' }) }) .then(response => response.json()) .then(result => { if (result.success) { // Payment succeeded window.location.href = '/success'; } else { // Payment failed displayError(result.error); } }); }

3. Process the payment on your server

   Process the payment on your server using the payment method token:

   // Server-side code (Node.js example) const VTransaction = require('@vtransactionexpert/vtransaction-js'); const vtransaction = new VTransaction('sk_test_51HG8K3JXhVORy8xG4tiQ2KovA98Xbdg'); app.post('/process-payment', async (req, res) => { const { payment_method_id, amount, currency } = req.body; try { const payment = await vtransaction.payments.create({ payment_method: payment_method_id, amount, currency, description: 'Order #12345', confirmation_method: 'automatic', confirm: true, return_url: 'https://yourwebsite.com/payment-confirmation' }); if (payment.status === 'succeeded') { // Payment successful res.json({ success: true }); } else if (payment.status === 'requires_action') { // Additional authentication required res.json({ success: false, requires_action: true, payment_intent_client_secret: payment.client_secret }); } else { // Payment failed res.json({ success: false, error: 'Payment failed' }); } } catch (error) { res.json({ success: false, error: error.message }); } });

4. Handle additional authentication if required

   If 3D Secure authentication is required, handle it on the client side:

   // Client-side JavaScript function handleServerResponse(response) { if (response.requires_action) { // Use client secret to handle 3D Secure authentication vtransactionClient.confirmCardPayment( response.payment_intent_client_secret ).then(function(result) { if (result.error) { // Authentication failed displayError(result.error.message); } else { // Authentication succeeded window.location.href = '/success'; } }); } else if (response.success) { // Payment succeeded window.location.href = '/success'; } else { // Payment failed displayError(response.error); } }

API Reference

For detailed information about API endpoints, parameters, and responses, refer to our API Documentation.

Support Resources

If you encounter any issues during integration or have questions, we offer several support resources:

Developer Support

• Developer Documentation: API Documentation
• Integration Support: Email [email protected]
• Developer Support Line: +1 (945) 995-0766 (Available Monday-Friday, 9 AM - 6 PM EST)

Additional Resources

• Frequently Asked Questions
• Code Examples Repository
• Developer Community Forum