API Documentation

Complete guide to integrating TransVoucher's payment processing API

Version 1.0 • Current: v1.0
View Service Availability

Quick Start

Get up and running with TransVoucher in minutes

1

Get API Credentials

Sign up and obtain your API key and secret from the merchant dashboard

2

Install SDK

Add one of our available SDKs or use direct API calls with your preferred language

3

Process Payments

Start accepting card payments and receive crypto settlements

Basic Payment Integration

JavaScript 
// Initialize TransVoucher
const transvoucher = new TransVoucher({
  apiKey: 'your-api-key',
  environment: 'sandbox' // or 'production'
});

// Create a payment
const payment = await transvoucher.payments.create({
  amount: 100.00,
  currency: 'USD',
  title: 'Product Purchase',
  description: 'Product purchase',
  reference_id: 'ORDER-123',
  customer_commission_percentage: 5,
  multiple_use: false,
  customer_details: {
    full_name: 'John Doe',             // Required if customer_details is provided
    id: 'cust_123',                    // Optional - Customer's unique identifier
    email: '[email protected]',      // Optional
    phone: '+1234567890',              // Optional
    date_of_birth: '1990-01-01',       // Optional - YYYY-MM-DD format
    country_of_residence: 'US',         // Optional - ISO country code
    state_of_residence: 'CA'           // Optional - Required if country is US
  },
  // Use metadata to identify customer/session - will be returned in webhooks and API responses
  metadata: {
    order_type: 'standard',
    product_id: 'PROD-456',
    user_id: 'user_789',
    session_id: 'sess_abc123'
  }
});

// Check payment status
if (transvoucher.payments.isCompleted(payment)) {
  console.log('Payment completed successfully');
}

// Redirect to payment page
window.location.href = payment.payment_url;

Authentication

API Key Authentication

TransVoucher uses API key and secret pairs to authenticate requests. Include both headers in every API request: 

X-API-Key: your-api-key
X-API-Secret: your-api-secret

Security Note: Never expose your API keys or secrets in client-side code. Always make API calls from your server and store credentials securely.

Example Request

curl -X POST https://api.transvoucher.com/v1.0/payment/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -H "X-API-Secret: your-api-secret" \
  -d '{
    "amount": 99.99,
    "currency": "USD",
    "customer_email": "[email protected]"
  }'

Webhook Signatures

Webhook events are signed with your endpoint secret to verify authenticity: 

// Verify webhook signature
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(computedSignature, 'hex')
  );
}

API Endpoints

Payments

POST /v1.0/payment/create

Create a new payment session

Parameters

Parameter Type Required Description
amount number Yes Payment amount (minimum 0.01)
currency string No Currency code (USD, EUR) - default: USD
title string Yes Title of the payment link
redirect_url string No Redirect URL
customer_details object No Customer information object. If provided, must include 'full_name'. Also supports: id, email, phone, date_of_birth (YYYY-MM-DD), country_of_residence (ISO code), state_of_residence (required for US)
metadata object No Use this to identify customer/session - will be returned in webhooks and API responses
theme object No UI theme customization
lang string No Language code (en, es, fr, de, it, pt, ru, zh, ja, ko)

Response

{
  "success": true,
  "data": {
    "transaction_id": 123,
    "reference_id": "txn_abc123...",
    "payment_url": "https://transvoucher.com/pay/...",
    "expires_at": "2024-01-01T12:00:00Z",
    "amount": 99.99,
    "currency": "USD",
    "status": "pending"
  }
}
GET /v1.0/payment/status/{referenceId}

Retrieve payment status by reference ID

Response

{
  "success": true,
  "data": {
    "transaction_id": 123,
    "reference_id": "txn_abc123...",
    "amount": 99.99,
    "currency": "USD",
    "status": "completed",
    "created_at": "2024-01-01T10:00:00Z",
    "updated_at": "2024-01-01T10:05:00Z",
    "paid_at": "2024-01-01T10:05:00Z",
    "payment_details": {
      "payment_id": "...",
      "status": "...",
      "payment_url": "..."
    }
  }
}
GET /v1.0/payment/list

List all payments with pagination and filtering

Query Parameters

Parameter Type Description
limit integer Number of results (1-100, default: 10)
page_token string Token for pagination (from previous response)
status string Filter by status (pending, completed, failed, expired)
from_date date Filter payments from this date (YYYY-MM-DD)
to_date date Filter payments to this date (YYYY-MM-DD)

Response

{
  "success": true,
  "data": {
    "payments": [
      {
        "transaction_id": 123,
        "reference_id": "txn_abc123...",
        "amount": 99.99,
        "currency": "USD",
        "status": "completed",
        "customer_details": {...},
        "metadata": {...},
        "created_at": "2024-01-01T10:00:00Z",
        "updated_at": "2024-01-01T10:05:00Z",
        "paid_at": "2024-01-01T10:05:00Z"
      }
    ],
    "has_more": true,
    "next_page_token": "eyJsYXN0X2lkIjoxMjN9",
    "count": 10
  }
}

Webhooks

Webhook Events

TransVoucher sends webhook events to notify your application of payment status changes to your configured webhook endpoint:

payment_intent.created

Sent when a payment intent is created

payment_intent.succeeded

Sent when a payment intent is successfully completed

payment_intent.failed

Sent when a payment intent fails or is declined

payment_intent.cancelled

Sent when a payment intent is cancelled

payment_intent.expired

Sent when a payment intent expires

SDK Integration

JavaScript SDK

Installation

npm install @transvoucher/sdk
or
yarn add @transvoucher/sdk

Usage

import TransVoucher from '@transvoucher/sdk';

const tv = new TransVoucher({
  apiKey: process.env.TRANSVOUCHER_API_KEY,
  environment: 'production' // or 'sandbox'
});

// Create payment
const payment = await tv.payments.create({
  amount: 99.99,                       // Required
  currency: 'USD',                     // Required
  title: 'Product Purchase',           // Required
  description: 'Product purchase',     // Optional
  reference_id: 'ORDER-123',          // Optional
  customer_commission_percentage: 5,   // Optional
  multiple_use: false,                // Optional
  customer_details: {
    full_name: 'John Doe',             // Required if customer_details is provided
    id: 'cust_123',                    // Optional - Customer's unique identifier
    email: '[email protected]',      // Optional
    phone: '+1234567890',              // Optional
    date_of_birth: '1990-01-01',       // Optional - YYYY-MM-DD format
    country_of_residence: 'US',         // Optional - ISO country code
    state_of_residence: 'CA'           // Optional - Required if country is US
  },
  // Use metadata to identify customer/session - will be returned in webhooks and API responses
  metadata: {
    order_type: 'standard',
    product_id: 'PROD-456',
    user_id: 'user_789',
    session_id: 'sess_abc123'
  }
});

// Helper methods for checking payment status
if (tv.payments.isCompleted(payment)) {
  console.log('Payment completed');
} else if (tv.payments.isPending(payment)) {
  console.log('Payment pending');
}

console.log('Payment URL:', payment.payment_url);

PHP SDK

Installation

composer require transvoucher/php-sdk

Usage

<?php
require_once 'vendor/autoload.php';

use TransVoucher\TransVoucher;

$transvoucher = new TransVoucher([
    'api_key' => $_ENV['TRANSVOUCHER_API_KEY'],
    'environment' => 'production'
]);

$payment = $transvoucher->payments->create([
    'amount' => 99.99,
    'currency' => 'USD',
    'title' => 'Product Purchase',
    'description' => 'Product purchase',
    'reference_id' => 'ORDER-123',
    'customer_commission_percentage' => 5,
    'multiple_use' => false,
    'customer_details' => [
        'full_name' => 'John Doe',             // Required if customer_details is provided
        'id' => 'cust_123',                    // Optional - Customer's unique identifier
        'email' => '[email protected]',      // Optional
        'phone' => '+1234567890',              // Optional
        'date_of_birth' => '1990-01-01',       // Optional - YYYY-MM-DD format
        'country_of_residence' => 'US',         // Optional - ISO country code
        'state_of_residence' => 'CA'           // Optional - Required if country is US
    ],
    // Use metadata to identify customer/session - will be returned in webhooks and API responses
    'metadata' => [
        'order_type' => 'standard',
        'product_id' => 'PROD-456',
        'user_id' => 'user_789',
        'session_id' => 'sess_abc123'
    ]
]);

// Helper methods for checking payment status
if ($payment->isCompleted()) {
    echo 'Payment completed';
} else if ($payment->isPending()) {
    echo 'Payment pending';
}

header('Location: ' . $payment->payment_url);
?>

Testing

Sandbox Environment

Use our sandbox environment to test your integration without processing real payments: 

Base URL: https://sandbox-api.transvoucher.com/v1.0

Test Card Numbers

Card Number Brand Result
4242424242424242 Visa Success
4000000000000002 Visa Declined
5555555555554444 Mastercard Success
4000000000000069 Visa Expired Card

Production Checklist

  • ✓ Test all payment flows in sandbox environment
  • ✓ Implement webhook endpoints and verify signatures
  • ✓ Handle error scenarios and edge cases
  • ✓ Secure API keys and never expose them client-side
  • ✓ Complete KYB verification for your merchant account
  • ✓ Update all endpoints to use /v1.0/ prefix for future compatibility

Need Help?

Our developer support team is here to help you integrate successfully

Technical Support

Get help with integration issues and technical questions

Contact via Telegram →

Email Support

Send detailed questions and receive comprehensive responses

[email protected] →

Help Center

Browse FAQs and common integration patterns

Visit Help Center →