API Documentation

Complete guide to integrating TransVoucher's payment processing API

Version 1.0 • Current: v1.0

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 our JavaScript SDK 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',
  description: 'Product purchase',
  customer: {
    email: '[email protected]'
  },
  successUrl: 'https://yoursite.com/success',
  cancelUrl: 'https://yoursite.com/cancel'
});

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

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, GBP) - default: USD
customer_email string No Customer email address
redirect_url string No Success redirect URL
close_url string No Cancel/close redirect URL
customer_details object No Customer information object
metadata object No Additional metadata for the payment
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://widget.wert.io/...",
    "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": {
      "wert_payment_id": "...",
      "wert_status": "...",
      "widget_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:

Webhook URL: POST /v1.0/payment/webhook

payment.completed

Sent when a payment is successfully completed

payment.failed

Sent when a payment fails or is declined

payment.refunded

Sent when a payment is refunded

settlement.processed

Sent when crypto settlement is completed

SDK Integration

JavaScript SDK

Installation

npm install @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,
  currency: 'USD',
  customer: {
    email: '[email protected]',
    name: 'John Doe'
  },
  successUrl: 'https://yourstore.com/success',
  cancelUrl: 'https://yourstore.com/cancel'
});

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

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',
    'customer' => [
        'email' => '[email protected]',
        'name' => 'John Doe'
    ],
    'success_url' => 'https://yourstore.com/success',
    'cancel_url' => 'https://yourstore.com/cancel'
]);

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

Python SDK

Installation

pip install transvoucher

Usage

import transvoucher
import os

client = transvoucher.Client(
    api_key=os.environ['TRANSVOUCHER_API_KEY'],
    environment='production'
)

payment = client.payments.create({
    'amount': 99.99,
    'currency': 'USD',
    'customer': {
        'email': '[email protected]',
        'name': 'John Doe'
    },
    'success_url': 'https://yourstore.com/success',
    'cancel_url': 'https://yourstore.com/cancel'
})

print(f"Payment URL: {payment.checkout_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 →