API Documentation - VTransaction Expert

Introduction

The VTransaction Expert API allows you to integrate our payment processing services directly into your applications, websites, or systems. Our RESTful API provides comprehensive functionality for managing payments, customers, subscriptions, and more.

Base URL: https://api.vtransactionexpert.com/v1

API Versioning

The current API version is v1. When a new version is released, we'll maintain the previous version for at least 12 months to give you time to migrate.

Request Format

All API requests should be made with HTTP(S) and include the following headers:

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_API_KEY

Authentication

All API requests must be authenticated using API keys. Your API keys carry many privileges, so be sure to keep them secure.

API Keys

There are two types of API keys:

Test keys - Used in your development and testing environments. Transactions made with test keys don't result in actual charges.
Live keys - Used in your production environment. Transactions made with live keys result in actual charges.

Important: Never share your API keys in publicly accessible areas such as GitHub, client-side code, etc.

Obtaining API Keys

You can obtain your API keys from the VTransaction Expert Merchant Center under Developer Settings. Each key is specific to your merchant account and should be kept confidential.

Authentication Example

curl -X GET https://api.vtransactionexpert.com/v1/customers \
  -H "Authorization: Bearer sk_test_51HG8K3JXhVORy8xG4tiQ2KovA98Xbdg"

Error Handling

The VTransaction Expert API uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

2xx - Success. The request was successfully received, understood, and accepted.
4xx - Client Error. The request contains bad syntax or cannot be fulfilled.
5xx - Server Error. The server failed to fulfill an apparently valid request.

Error Response Format

When an error occurs, the API will return a JSON object with the following structure:

{
  "error": {
    "code": "resource_not_found",
    "message": "The requested resource was not found.",
    "param": "customer_id",
    "request_id": "req_9GvNgq2IEZqh7v"
  }
}

Common Error Codes

Code	Description	HTTP Status
authentication_error	Authentication with the provided credentials failed	401
invalid_request	The request was unacceptable, often due to missing a required parameter	400
resource_not_found	The requested resource does not exist	404
rate_limit_exceeded	Too many requests hit the API too quickly	429
api_error	An error occurred on our servers	500

Create Payment

Creates a new payment and processes it using the provided payment method. You can create payments using credit cards, bank accounts, or tokens from stored payment methods.

POST /payments

Request Parameters

Parameter	Description	Type	Required
amount	Amount to charge (in cents). For example, $10.00 would be 1000.	Integer	Yes
currency	Three-letter ISO currency code (e.g., USD, CAD).	String	Yes
payment_method	The payment method to use. Can be a token, credit card object, or bank account object.	Object	Yes
description	Description of the payment that appears on statements.	String	No
customer_id	ID of an existing customer if this payment is associated with a customer.	String	No
metadata	Set of key-value pairs for storing additional information about the payment.	Object	No
capture	Whether to capture the payment immediately or just authorize it. Default is true.	Boolean	No

Example Request

curl -X POST https://api.vtransactionexpert.com/v1/payments \
  -H "Authorization: Bearer sk_test_51HG8K3JXhVORy8xG4tiQ2KovA98Xbdg" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000,
    "currency": "usd",
    "payment_method": {
      "type": "card",
      "card": {
        "number": "4242424242424242",
        "exp_month": 8,
        "exp_year": 2025,
        "cvc": "314"
      }
    },
    "description": "Payment for order #12345",
    "metadata": {
      "order_id": "12345",
      "customer_name": "John Smith"
    }
  }'

Response

{
  "id": "pay_8KgLH2p9TY6RzV",
  "object": "payment",
  "amount": 2000,
  "amount_refunded": 0,
  "currency": "usd",
  "status": "succeeded",
  "description": "Payment for order #12345",
  "payment_method": "pm_1HG8nWJXhVORy8xG5TpU8MnL",
  "payment_method_details": {
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "4242",
      "exp_month": 8,
      "exp_year": 2025
    }
  },
  "metadata": {
    "order_id": "12345",
    "customer_name": "John Smith"
  },
  "created": 1619456789,
  "captured": true,
  "receipt_url": "https://receipt.vtransactionexpert.com/pay_8KgLH2p9TY6RzV"
}

Retrieve Payment

Retrieves the details of a previously created payment.

GET /payments/{payment_id}

Path Parameters

Parameter	Description	Type	Required
payment_id	The ID of the payment to retrieve.	String	Yes

Example Request

curl -X GET https://api.vtransactionexpert.com/v1/payments/pay_8KgLH2p9TY6RzV \
  -H "Authorization: Bearer sk_test_51HG8K3JXhVORy8xG4tiQ2KovA98Xbdg"

Response

{
  "id": "pay_8KgLH2p9TY6RzV",
  "object": "payment",
  "amount": 2000,
  "amount_refunded": 0,
  "currency": "usd",
  "status": "succeeded",
  "description": "Payment for order #12345",
  "payment_method": "pm_1HG8nWJXhVORy8xG5TpU8MnL",
  "payment_method_details": {
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "4242",
      "exp_month": 8,
      "exp_year": 2025
    }
  },
  "metadata": {
    "order_id": "12345",
    "customer_name": "John Smith"
  },
  "created": 1619456789,
  "captured": true,
  "receipt_url": "https://receipt.vtransactionexpert.com/pay_8KgLH2p9TY6RzV"
}

SDK Libraries

To simplify integration with our API, we provide SDK libraries for several popular programming languages:

Official Libraries

JavaScript/Node.js: vtransaction-node
PHP: vtransaction-php
Python: vtransaction-python
Ruby: vtransaction-ruby
Java: vtransaction-java
.NET: vtransaction-dotnet

JavaScript Example

// Install with: npm install @vtransactionexpert/vtransaction-js

const VTransaction = require('@vtransactionexpert/vtransaction-js');
const vtransaction = new VTransaction('sk_test_51HG8K3JXhVORy8xG4tiQ2KovA98Xbdg');

async function createPayment() {
  try {
    const payment = await vtransaction.payments.create({
      amount: 2000,
      currency: 'usd',
      payment_method: {
        type: 'card',
        card: {
          number: '4242424242424242',
          exp_month: 8,
          exp_year: 2025,
          cvc: '314'
        }
      },
      description: 'Payment for order #12345'
    });
    
    console.log('Payment created:', payment.id);
    return payment;
  } catch (error) {
    console.error('Error creating payment:', error);
  }
}

createPayment();

Testing

Testing your integration before going live is essential. VTransaction Expert provides a sandbox environment for testing without processing real payments.

Test Environment

To use the test environment, simply use your test API keys instead of your live keys. All API requests will behave the same way, but no actual charges will occur.

Test Credit Card Numbers

You can use the following test card numbers to simulate different scenarios:

Card Number	Brand	Scenario
4242424242424242	Visa	Successful payment
4000000000000002	Visa	Declined payment (generic decline)
4000000000000069	Visa	Declined payment (expired card)
4000000000000127	Visa	Declined payment (incorrect CVC)
5555555555554444	Mastercard	Successful payment
378282246310005	American Express	Successful payment

Note: For any test card, you can use any future expiration date, any 3-digit CVC (4 digits for American Express), and any ZIP code.

Support

If you encounter any issues or have questions about the API, our support team is here to help.

Contact Methods

Email: [email protected]
Developer Support Line: +1 (945) 995-0766
Developer Portal: https://developers.vtransactionexpert.com

Additional Resources

Integration Guide - Step-by-step instructions for common integration scenarios
FAQ - Answers to frequently asked questions
Code Examples - Repository of implementation examples in various languages

When contacting support about a specific issue, please include:

Your merchant account ID
Any relevant payment or request IDs
Details about the issue you're experiencing
Code samples or error messages (with sensitive information removed)