VelaPay API Developer Portal

Introduction

VelaPay provides two distinct APIs for payment processing and terminal management:

Local Terminal API (In-Network): Direct communication with VelaPay terminals on your local network for real-time payment processing, device control, and terminal management.
Cloud Payment API: Cloud-based payment processing service for processing card-not-present transactions through configured payment processors without requiring a physical terminal.

This documentation covers both APIs comprehensively, providing all the information needed to integrate VelaPay into your payment solutions.

Getting Started

Prerequisites

For Local Terminal API:

VelaPay Manager application installed on a compatible terminal
Terminal connected to your local network
Terminal's IP address
Store secret (for remote authentication)

For Cloud Payment API:

API Key and API Secret (contact VelaPay Support)
HTTPS-capable client
Server time synchronized with UTC

Quick Decision Guide

Use Local Terminal API when you need to:

Process card-present transactions with physical terminals
Control terminal hardware (printer, camera, MSR)
Display dialogs and collect customer input on terminal
Capture signatures
Manage terminal configuration
Access terminal device information

Use Cloud Payment API when you need to:

Process card-not-present transactions (e-commerce, phone orders)
Process payments without physical terminal hardware
Integrate with web applications or remote services
Tokenize card data for recurring payments
Process transactions through configured payment gateways

Best Practices

General Best Practices

Request IDs: Always include a requestId for payment transactions to enable request/response logging and retrieval.
Timeout Handling: Implement appropriate timeout handling on the client side, especially for payment and dialog requests that may require customer interaction.
Error Recovery: Always check the status field in responses and handle errors appropriately with proper retry logic.
Amount Formatting: Always send amounts as strings in decimal format (e.g., "10.00" for $10.00) for Local Terminal API. Use numeric values for Cloud Payment API.
Concurrent Requests: Avoid sending multiple payment requests simultaneously as they will be rejected with "Another transaction in process" error.
Signature Generation: Always compute the signature using the exact request body that will be sent (including whitespace and formatting).

Authentication Best Practices

Secure Secret Storage: Store secrets and API keys securely and never expose them in client-side code. Use environment variables or secure key management systems. Never commit secrets to version control.
HMAC-SHA256 Authentication: Use proper HMAC-SHA256 authentication with timestamp validation. Ensure server and client clocks are synchronized (use NTP if possible). Handle "Request timestamp expired" errors by checking clock synchronization.
API Key Management: Rotate API keys periodically. Use different API keys for development and production. Monitor API key usage for suspicious activity.

Cloud Payment API Best Practices

PCI Compliance: Never store unencrypted card data. Use tokenization for recurring payments. Implement proper data encryption in transit (HTTPS). Follow PCI DSS requirements for card data handling.
Transaction Management: Store transaction IDs for refund/void operations. Implement idempotency for duplicate prevention. Log all transaction requests and responses.
Error Handling: Implement retry logic for network failures. Handle declined transactions appropriately. Provide clear error messages to users.

Support

Contact Information

For API access, credentials, technical support, or questions about VelaPay APIs:

VelaPay Support

Website: https://www.velapay.net
Email: support@velapay.net

Getting API Credentials

For Cloud Payment API:

Contact VelaPay Support to obtain your API Key and API Secret
Specify your intended use case and estimated transaction volume
Receive credentials and base URL for production environment

For Local Terminal API:

The store secret is configured in the VelaPay Manager application on each terminal
Contact VelaPay Support for assistance with terminal configuration
No registration required for localhost access

Local Terminal API

Direct HTTP communication with VelaPay terminals on your local network for real-time payment processing, device control, and terminal management.

💳

Payment Processing

Card-present transactions with EMV, NFC, and MSR support

📱

Terminal Control

Display dialogs, collect input, and manage screen navigation

🖨️

Hardware Integration

Printer, camera, and magnetic stripe reader control

⚙️

Configuration

Terminal settings and cloud configuration management

Getting Started

VelaPay Manager serves as a universal payment middleware running on Android terminals, providing HTTP API access on port 7501 for payment processing and device management.

Prerequisites

VelaPay Manager application installed on a compatible terminal
Terminal connected to your local network
Terminal's IP address (find in VelaPay Manager settings)
Store secret (for remote authentication - configured in terminal settings)

Server Configuration

Port: 7501
Protocol: HTTP
Content-Type: application/json; charset=utf-8
CORS: Enabled for all origins
Base URL: http://[terminal-ip]:7501

Authentication

Local Requests

Requests from localhost (127.0.0.1 or ::1) do not require authentication.

Remote Requests - HMAC-SHA256 Signature

Remote requests require cryptographic signature authentication using HMAC-SHA256:

X-Timestamp: Current Unix timestamp in seconds (epoch time)
X-Signature: HMAC-SHA256(secret, timestamp + body)
The secret is configured in store_secret and is never transmitted
Timestamps must be within 5 minutes of server time (prevents replay attacks)

Signature Calculation Example (JavaScript)

const crypto = require('crypto');

function generateSignature(secret, timestamp, body) {
    const message = timestamp + body;
    return crypto.createHmac('sha256', secret)
        .update(message)
        .digest('hex');
}

const timestamp = Math.floor(Date.now() / 1000).toString();
const body = JSON.stringify({ requestType: 'payment', amount: '100.00' });
const signature = generateSignature(secret, timestamp, body);

Request/Response Format

Base Request Structure

{
  "requestType": "string",  // Required: Type of request
  "resourceType": "string", // Context-specific resource
  "actionType": "string",   // Context-specific action
  "requestId": "string",    // Optional: For logging
  // Additional parameters...
}

Base Response Structure

{
  "status": "ok|error",
  "timestamp": 1234567890000,
  "version": "1.0.0",
  "message": "string",
  // Additional data...
}

Supported Payment Types

VelaPay Manager supports all major payment types for in-person transactions:

Credit/Debit Cards: Visa, Mastercard, Amex, Discover
EMV Chip: Full EMV compliance for card-present transactions
Contactless: NFC tap-to-pay support
EBT: Electronic Benefits Transfer processing
Gift Cards: Integrated gift card management system

API Request Types

system

App control, configuration, logs, screenshots

device

Device information and terminal status

payment

Sale, auth, capture, return, batch settlement

dialog

Customer input, signature capture, button prompts

print

Receipt printing and custom templates

msr

Magnetic stripe card reader

System API

The System API provides access to application management, configuration, logging, and screen capture.

Request Parameters

Parameter	Type	Required	Description	Valid Values
`requestType`	string	Required	Type of request	"system"
`resourceType`	string	Required	Resource to access	"app", "config", "log", "screen"
`actionType`	string	Required	Action to perform (varies by resourceType)	See specific endpoints below

POST Restart Application

Parameters:

Parameter	Type	Required	Description
`requestType`	string	Required	Must be "system"
`resourceType`	string	Required	Must be "app"
`actionType`	string	Required	Must be "restart"

// Request
{
  "requestType": "system",
  "resourceType": "app",
  "actionType": "restart"
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0"
}

POST Capture Screenshot

Parameters:

Parameter	Type	Required	Description
`requestType`	string	Required	Must be "system"
`resourceType`	string	Required	Must be "screen"
`actionType`	string	Required	Must be "capture"

Response Fields:

Field	Type	Description
`status`	string	Response status: "ok" or "error"
`imageData`	string	Base64-encoded PNG image data
`format`	string	Image format (always "png")

// Request
{
  "requestType": "system",
  "resourceType": "screen",
  "actionType": "capture"
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0",
  "imageData": "base64_encoded_png_data",
  "format": "png"
}

POST Get Log List

Request Parameters:

Parameter	Type	Required	Description
`requestType`	string	Required	Must be "system"
`resourceType`	string	Required	Must be "log"
`logType`	string	Required	Type of logs to retrieve (e.g., "requestResult")
`actionType`	string	Required	"get", "getList", or "clear"
`logId`	string	Optional	Specific log ID (required when actionType is "get")
`logFilter`	object	Optional	Filter criteria for log retrieval
`logFilter.createdSince`	integer	Optional	Unix timestamp in milliseconds - retrieve logs created since this time

// Request
{
  "requestType": "system",
  "resourceType": "log",
  "logType": "requestResult",
  "actionType": "getList",
  "logFilter": {
    "createdSince": 1234567890000
  }
}

// Response
{
  "status": "ok",
  "logs": [...],
  "count": 10
}

Device API

Retrieve device information and terminal status.

GET Get Device Info

// Request
{
  "requestType": "device",
  "resourceType": "info"
}

// Response
{
  "status": "ok",
  "uid": "GN1234567890",
  "manufacture": "GENERIC",
  "model": "GENERIC",
  "sn": "1234567890"
}

Payment API

Process card-present transactions including sale, authorization, capture, refund, and batch settlement.

Transaction Types

sale - Regular sale transaction
auth - Authorization only
capture - Capture a previous authorization
return - Return/refund transaction
void - Void transaction
adjust - Adjust tip amount
batch - Batch settlement

Tender Types

credit - Credit card
debit - Debit card
EBT - Electronic Benefits Transfer
gift - Gift card
loyalty - Loyalty card

Payment Request Parameters

Parameter	Type	Required	Description	Valid Values / Example
`requestType`	string	Required	Type of request	"payment"
`actionType`	string	Optional	Action to perform	"process"
`transactionType`	string	Required	Type of payment transaction	"sale", "auth", "capture", "return", "void", "adjust", "batch"
`amount`	string	Required	Transaction amount in decimal format	"100.00", "25.99"
`tenderType`	string	Optional	Payment method type. If not provided, user will be prompted to select	"credit", "debit", "EBT", "gift", "loyalty"
`amountTip`	string	Optional	Pre-set tip amount	"10.00", "5.50"
`invoiceNumber`	string	Optional	Invoice or order number for reference	"INV-12345", "ORDER-001"
`referenceNumber`	string	Conditional	Required for capture, void, and adjust transactions. Transaction reference from original auth	"REF123456"
`signatureCapture`	boolean	Optional	Request signature capture after approval	true, false
`requestId`	string	Optional	Unique identifier for logging and retrieval	"unique_request_id"
`company`	string	Optional	Company name for receipt	"ACME Corp"
`printReceipt`	string	Optional	Whether to print receipt automatically	"true", "false"

Tip Prompt Parameters

Optional parameters for customizing tip prompts during payment:

Parameter	Type	Required	Description
`tipPrompt`	string	Optional	Tip prompt style: "button" for preset options, "custom" for manual entry
`tip1Label`	string	Optional	Label for first tip option (e.g., "15%")
`tip1Amount`	string	Optional	Amount for first tip option
`tip2Label`	string	Optional	Label for second tip option (e.g., "18%")
`tip2Amount`	string	Optional	Amount for second tip option
`tip3Label`	string	Optional	Label for third tip option (e.g., "20%")
`tip3Amount`	string	Optional	Amount for third tip option
`tipShowCustomTip`	boolean	Optional	Show "Custom Tip" button for manual entry
`tipShowNoTip`	boolean	Optional	Show "No Tip" button option

Payment Response Fields

Field	Type	Description	Example Value
`status`	string	Overall request status	"ok", "error"
`timestamp`	integer	Response timestamp in milliseconds	1234567890000
`version`	string	API version	"1.0.0"
`paymentStatus`	string	Payment transaction status	"APPROVED", "DECLINED", "ERROR"
`batchID`	string	Current batch identifier	"123"
`transactionID`	string	Unique transaction identifier from processor	"456789"
`transactionNumber`	string	Local transaction number	"789"
`transactionType`	string	Type of transaction performed	"SALE", "AUTH", "CAPTURE", etc.
`tenderType`	string	Payment method used	"CREDIT", "DEBIT"
`amount`	string	Final transaction amount	"100.00"
`amountTip`	string	Tip amount included	"10.00"
`amountCashBack`	string	Cash back amount (if applicable)	"0.00"
`amountRequest`	string	Originally requested amount	"100.00"
`invoiceNumber`	string	Invoice number from request	"INV-123"
`referenceNumber`	string	Transaction reference (use for capture/void/adjust)	"REF123"
`authCode`	string	Authorization code from processor	"AUTH456"
`resultCode`	string	Result code from processor	"00" (success)
`token`	string	Tokenized card data (if tokenization enabled)	"tokenized_card_data"
`token2`	string	Additional token data	"additional_token"
`cardEntry`	string	Card entry method	"CHIP", "SWIPE", "MANUAL", "CONTACTLESS"
`merchantID`	string	Merchant identifier	"MERCHANT123"
`cardType`	string	Card brand	"VISA", "MASTERCARD", "AMEX", "DISCOVER"
`cardNumber`	string	Masked card number (last 4 digits)	"****1234"
`cardHolder`	string	Cardholder name from card	"JOHN DOE"
`signatureData`	string	Base64-encoded signature image (if captured)	"base64_signature"
`message`	string	Response message or error description	"Transaction approved"

Batch Settlement Response Fields

Additional fields returned for batch settlement transactions:

Field	Type	Description
`batch_settlementTime`	string	Batch settlement timestamp (ISO format)
`batch_creditSaleCount`	string	Number of credit card sale transactions
`batch_creditSaleAmount`	string	Total amount of credit card sales
`batch_creditReturnCount`	string	Number of credit card return transactions
`batch_creditReturnAmount`	string	Total amount of credit card returns
`batch_debitSaleCount`	string	Number of debit card sale transactions
`batch_debitSaleAmount`	string	Total amount of debit card sales
`batch_debitReturnCount`	string	Number of debit card return transactions
`batch_debitReturnAmount`	string	Total amount of debit card returns

POST Process Sale

// Request
{
  "requestType": "payment",
  "actionType": "process",
  "transactionType": "sale",
  "tenderType": "credit",
  "amount": "100.00",
  "amountTip": "10.00",
  "invoiceNumber": "INV-123",
  "signatureCapture": true,
  "tipPrompt": "button",
  "tip1Label": "15%",
  "tip1Amount": "15.00",
  "tip2Label": "18%",
  "tip2Amount": "18.00",
  "tip3Label": "20%",
  "tip3Amount": "20.00",
  "tipShowCustomTip": true,
  "tipShowNoTip": true,
  "company": "ACME Corp",
  "printReceipt": "true",
  "requestId": "unique_request_id"
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0",
  "paymentStatus": "APPROVED",
  "batchID": "123",
  "transactionID": "456789",
  "transactionType": "SALE",
  "tenderType": "CREDIT",
  "amount": "100.00",
  "amountTip": "10.00",
  "amountCashBack": "0.00",
  "amountRequest": "100.00",
  "invoiceNumber": "INV-123",
  "resultCode": "00",
  "token": "tokenized_card_data",
  "token2": "additional_token",
  "cardEntry": "CHIP",
  "transactionNumber": "789",
  "referenceNumber": "REF123",
  "authCode": "AUTH456",
  "merchantID": "MERCHANT123",
  "cardType": "VISA",
  "cardNumber": "****1234",
  "cardHolder": "JOHN DOE",
  "signatureData": "base64_signature"
}

POST Batch Settlement

// Request
{
  "requestType": "payment",
  "transactionType": "batch"
}

// Response
{
  "status": "ok",
  "batch_settlementTime": "2023-12-01T10:00:00Z",
  "batch_creditSaleCount": "10",
  "batch_creditSaleAmount": "1000.00",
  "batch_creditReturnCount": "2",
  "batch_creditReturnAmount": "50.00",
  "batch_debitSaleCount": "5",
  "batch_debitSaleAmount": "250.00",
  "batch_debitReturnCount": "1",
  "batch_debitReturnAmount": "25.00"
}

Dialog API

Display customer input dialogs, signature capture, and button prompts on the terminal screen.

Dialog Types

input - Collect various types of user input (number, phone, money, email, date, time)
signature - Capture customer signature
button - Display multiple button options (up to 5 buttons)

Common Dialog Parameters

Parameter	Type	Required	Description
`requestType`	string	Required	Must be "dialog"
`dialogType`	string	Required	Type of dialog: "input", "signature", or "button"
`title`	string	Optional	Dialog title (supports HTML formatting)
`description`	string	Optional	Dialog description or instructions
`timeout`	integer	Optional	Timeout in seconds (dialog will auto-close after this time)

Input Dialog Specific Parameters

Parameter	Type	Required	Description	Valid Values
`inputType`	string	Required	Type of input to collect	"number", "phone", "money", "email", "date", "time", "datetime"

Input Dialog Response Fields:

Field	Type	Description
`inputValue`	string	Raw input value entered by user
`inputValueFormatted`	string	Formatted value (for money type, formatted with decimals)

Button Dialog Specific Parameters

Support for up to 5 buttons with customizable labels and return values:

Parameter	Type	Required	Description
`button1Label`	string	Optional	Text displayed on first button
`button1Value`	string	Optional	Value returned when first button is clicked
`button2Label`	string	Optional	Text displayed on second button
`button2Value`	string	Optional	Value returned when second button is clicked
`button3Label`	string	Optional	Text displayed on third button
`button3Value`	string	Optional	Value returned when third button is clicked
`button4Label`	string	Optional	Text displayed on fourth button
`button4Value`	string	Optional	Value returned when fourth button is clicked
`button5Label`	string	Optional	Text displayed on fifth button
`button5Value`	string	Optional	Value returned when fifth button is clicked

Button Dialog Response Fields:

Field	Type	Description
`buttonLabel`	string	Label of the button that was clicked
`buttonValue`	string	Value associated with the button that was clicked

Signature Dialog Specific Parameters

Parameter	Type	Required	Description
`description`	string	Optional	Agreement text or instructions (e.g., "I agree to pay...")

Signature Dialog Response Fields:

Field	Type	Description
`signatureData`	string	Base64-encoded PNG image of the signature

POST Button Dialog

// Request
{
  "requestType": "dialog",
  "dialogType": "button",
  "title": "Select Option",
  "description": "Choose an option",
  "button1Label": "Option 1",
  "button2Label": "Option 2",
  "button3Label": "Option 3",
  "button4Label": "Option 4",
  "button5Label": "Option 5",
  "button1Value": "value1",
  "button2Value": "value2",
  "button3Value": "value3",
  "button4Value": "value4",
  "button5Value": "value5"
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0",
  "buttonLabel": "Option 2",
  "buttonValue": "value2"
}

POST Input Dialog

Supported input types: number, phone, money, email, date, time, datetime

// Request
{
  "requestType": "dialog",
  "dialogType": "input",
  "inputType": "money",
  "title": "Enter Amount",
  "timeout": 30
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0",
  "inputValue": "1000",
  "inputValueFormatted": "10.00"
}

POST Signature Dialog

// Request
{
  "requestType": "dialog",
  "dialogType": "signature",
  "title": "APPROVEDSignature Required",
  "description": "I agree to pay the above total amount according to the card issuer agreement",
  "timeout": 60
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0",
  "signatureData": "base64_encoded_signature_image"
}

Print API

Print receipts and custom templates using the terminal's built-in printer.

Print Types

image - Print a base64-encoded image
template - Print using a structured template with multiple item types

Common Print Parameters

Parameter	Type	Required	Description
`requestType`	string	Required	Must be "print"
`printType`	string	Required	Type of print job: "image" or "template"

Image Print Parameters

Parameter	Type	Required	Description
`imageData`	string	Required	Base64-encoded image data (PNG, JPG, or other supported formats)

Template Print Parameters

Parameter	Type	Required	Description
`printItemList`	array	Required	Array of print item objects, each defining a specific element to print

Print Item Types

Each item in printItemList must have a type field. Supported types:

Text Item

Property	Type	Required	Description	Valid Values
`type`	string	Required	Item type	"text"
`fontSize`	string	Optional	Font size	"small", "medium", "large", "xlarge"
`textLeft`	string	Optional	Text aligned to left	Any string
`textCenter`	string	Optional	Text aligned to center	Any string
`textRight`	string	Optional	Text aligned to right	Any string
`isBold`	boolean	Optional	Apply bold formatting	true, false
`isItalic`	boolean	Optional	Apply italic formatting	true, false
`isUnderline`	boolean	Optional	Apply underline formatting	true, false
`isInvert`	boolean	Optional	Invert colors (white text on black background)	true, false

Barcode Item

Property	Type	Required	Description	Valid Values
`type`	string	Required	Item type	"barcode"
`code`	string	Optional	Barcode data to encode	Any string
`format`	string	Optional	Barcode format	"code128", "code39", "upc"
`width`	integer	Optional	Barcode width in pixels	e.g., 300
`height`	integer	Optional	Barcode height in pixels	e.g., 100
`alignment`	string	Optional	Barcode alignment	"left", "center", "right"

QR Code Item

Property	Type	Required	Description	Valid Values
`type`	string	Required	Item type	"qrcode"
`code`	string	Optional	Data to encode in QR code (e.g., URL, text)	Any string
`height`	integer	Optional	QR code size in pixels	e.g., 200
`alignment`	string	Optional	QR code alignment	"left", "center", "right"

Line Item

Property	Type	Required	Description
`type`	string	Required	Must be "line"
`height`	integer	Optional	Line thickness in pixels (default: 1)

Feed Item

Property	Type	Required	Description
`type`	string	Required	Must be "feed"
`height`	integer	Optional	Feed distance in pixels (advances paper without printing)

Cut Item

Property	Type	Required	Description
`type`	string	Required	Must be "cut" - triggers paper cutter (no additional properties)

POST Print Image

// Request
{
  "requestType": "print",
  "printType": "image",
  "imageData": "base64_encoded_image_data"
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0"
}

POST Print Template

// Request
{
  "requestType": "print",
  "printType": "template",
  "printItemList": [
    {
      "type": "text",
      "fontSize": "large",
      "textCenter": "Receipt",
      "isBold": true,
      "isUnderline": true
    },
    {
      "type": "text",
      "textLeft": "Item",
      "textRight": "$10.00"
    },
    {
      "type": "line",
      "height": 2
    },
    {
      "type": "qrcode",
      "code": "https://example.com",
      "height": 200,
      "alignment": "center"
    },
    {
      "type": "barcode",
      "code": "123456789",
      "format": "code128",
      "width": 300,
      "height": 100,
      "alignment": "center"
    },
    {
      "type": "feed",
      "height": 50
    },
    {
      "type": "cut"
    }
  ]
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0"
}

MSR API

Magnetic stripe reader operations for reading card data.

Request Parameters

Parameter	Type	Required	Description	Valid Values
`requestType`	string	Required	Type of request	"msr"
`actionType`	string	Required	Action to perform	"read"

Response Fields

Field	Type	Description	Example
`status`	string	Response status	"ok", "error"
`track1`	string	Track 1 data from magnetic stripe	Raw track data
`track2`	string	Track 2 data from magnetic stripe	Raw track data
`track3`	string	Track 3 data from magnetic stripe	Raw track data
`cardNumber`	string	Masked card number (last 4 digits visible)	"****1234"
`expiryDate`	string	Card expiry date in MMYY format	"1225" (December 2025)
`cardholderName`	string	Cardholder name from track data	"JOHN DOE"

POST Read Card (MSR)

// Request
{
  "requestType": "msr",
  "actionType": "read"
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0",
  "track1": "...",
  "track2": "...",
  "track3": "...",
  "cardNumber": "****1234",
  "expiryDate": "1225",
  "cardholderName": "JOHN DOE"
}

Note: The device will automatically display a "SWIPE" screen and wait for the user to swipe their card through the magnetic stripe reader.

Local Terminal API Tester

Terminal URL

Method

Request Body (JSON)

Authentication (Optional for Remote)

Response

No request sent yet

Complete Integration Example

This example demonstrates a complete payment flow with the Local Terminal API.

JavaScript/Node.js Example

const crypto = require('crypto');
const fetch = require('node-fetch');

class VelaPayTerminalClient {
    constructor(terminalIp, secret) {
        this.baseUrl = `http://${terminalIp}:7501`;
        this.secret = secret;
    }

    generateSignature(timestamp, body) {
        const message = timestamp + body;
        return crypto
            .createHmac('sha256', this.secret)
            .update(message)
            .digest('hex');
    }

    async makeRequest(payload) {
        const timestamp = Math.floor(Date.now() / 1000).toString();
        const body = JSON.stringify(payload);
        const signature = this.generateSignature(timestamp, body);

        const response = await fetch(this.baseUrl, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'X-Timestamp': timestamp,
                'X-Signature': signature
            },
            body: body
        });

        return response.json();
    }

    async processPayment(amount, options = {}) {
        const requestId = options.requestId || `ORDER-${Date.now()}`;

        const paymentRequest = {
            requestType: "payment",
            transactionType: "sale",
            amount: amount,
            signatureCapture: options.signatureCapture || true,
            requestId: requestId,
            invoiceNumber: options.invoiceNumber,

            tipPrompt: "button",
            tip1Label: "15%",
            tip1Amount: (parseFloat(amount) * 0.15).toFixed(2),
            tip2Label: "18%",
            tip2Amount: (parseFloat(amount) * 0.18).toFixed(2),
            tip3Label: "20%",
            tip3Amount: (parseFloat(amount) * 0.20).toFixed(2),
            tipShowCustomTip: true,
            tipShowNoTip: true
        };

        return this.makeRequest(paymentRequest);
    }
}

// Usage
const client = new VelaPayTerminalClient('192.168.1.100', 'your-secret-key');
const result = await client.processPayment('50.00', {
    invoiceNumber: 'INV-12345',
    signatureCapture: true
});

console.log('Payment Result:', result);

Python Example

import hmac
import hashlib
import time
import json
import requests

class VelaPayTerminalClient:
    def __init__(self, terminal_ip, secret):
        self.base_url = f'http://{terminal_ip}:7501'
        self.secret = secret

    def generate_signature(self, timestamp, body):
        message = str(timestamp) + body
        return hmac.new(
            self.secret.encode('utf-8'),
            message.encode('utf-8'),
            hashlib.sha256
        ).hexdigest()

    def make_request(self, payload):
        timestamp = str(int(time.time()))
        body = json.dumps(payload)
        signature = self.generate_signature(timestamp, body)

        headers = {
            'Content-Type': 'application/json',
            'X-Timestamp': timestamp,
            'X-Signature': signature
        }

        response = requests.post(self.base_url, headers=headers, data=body)
        return response.json()

    def process_payment(self, amount, **options):
        request_id = options.get('request_id', f'ORDER-{int(time.time())}')

        payment_request = {
            'requestType': 'payment',
            'transactionType': 'sale',
            'amount': amount,
            'signatureCapture': options.get('signature_capture', True),
            'requestId': request_id,
            'invoiceNumber': options.get('invoice_number'),

            'tipPrompt': 'button',
            'tip1Label': '15%',
            'tip1Amount': f'{float(amount) * 0.15:.2f}',
            'tip2Label': '18%',
            'tip2Amount': f'{float(amount) * 0.18:.2f}',
            'tip3Label': '20%',
            'tip3Amount': f'{float(amount) * 0.20:.2f}',
            'tipShowCustomTip': True,
            'tipShowNoTip': True
        }

        return self.make_request(payment_request)

# Usage
client = VelaPayTerminalClient('192.168.1.100', 'your-secret-key')
result = client.process_payment('75.50', invoice_number='INV-67890')
print(f"Payment Result: {result}")

Cloud Payment API - Overview

The VelaPay Cloud Payment API provides a cloud-based payment processing service accessible over HTTPS. Unlike the Local Terminal API which controls physical terminals, the Cloud Payment API processes payments through configured payment processors in the cloud.

Key Characteristics

HTTPS-based cloud service
API Key + HMAC-SHA256 authentication required for all requests
Card-not-present transaction processing
Tokenization support for recurring payments
Integration with multiple payment gateways

Authentication

All Cloud Payment API requests require HMAC-SHA256 authentication.

Required Headers

X-API-Key: Your API Key
X-Timestamp: Current Unix timestamp in seconds
X-Signature: HMAC-SHA256 signature
Content-Type: application/json

Computing the Signature

const crypto = require('crypto');

function generateSignature(apiSecret, timestamp, body) {
    const message = timestamp + body;
    return crypto
        .createHmac('sha256', apiSecret)
        .update(message)
        .digest('hex');
}

Server Configuration

Protocol: HTTPS
Port: 443
Base URL: Contact VelaPay for production URL
Content-Type: application/json
API Version: v1

Request Parameters

Common Request Parameters

Parameter	Type	Required	Description	Valid Values / Example
`requestType`	string	Required	Type of request	"payment"
`actionType`	string	Required	Action to perform	"process"
`transactionType`	string	Required	Type of payment transaction	"sale", "auth", "capture", "void", "return", "token", "delete"
`amount`	string	Conditional	Transaction amount (required for sale, auth, return; optional for capture; not used for void, delete, token)	"10.00", "125.99"
`invoiceNumber`	string	Optional	Invoice or order number for reference	"INV-12345", "ORDER-001"
`email`	string	Optional	Customer email address	"customer@example.com"
`getToken`	boolean	Optional	Request card tokenization for future use	true, false
`referenceNumber`	string	Conditional	Required for capture, void, return, delete transactions. Transaction reference from original transaction	"281025O2C-F1437148-..."
`customerIp`	string	Optional	Customer IP address - Strongly recommended for fraud detection and transaction security	"192.168.1.100"

Transaction Type Requirements

Transaction Type	Amount Required	Card Info Required	Reference Number Required	Description
`sale`	✓ Yes	✓ Yes	✗ No	Complete sale transaction with immediate charge
`auth`	✓ Yes	✓ Yes	✗ No	Authorization only (funds held, not captured)
`capture`	Optional	✗ No	✓ Yes	Capture previously authorized amount (full or partial)
`void`	✗ No	✗ No	✓ Yes	Cancel/void a sale or return transaction
`return`	Optional	✗ No	✓ Yes	Refund a previous transaction (full or partial)
`token`	✗ No ("0.00")	✓ Yes	✗ No	Tokenize card without charging (amount must be "0.00")
`delete`	✗ No	✗ No	✓ Yes	Cancel/delete an authorization before capture

Card Information Parameters

Option 1: New Card Details (Required for sale, auth, token transactions)

Parameter	Type	Required	Description	Example
`cardNumber`	string	Required	Credit card number (16 digits typically)	"4111111111111111"
`cardExpDate`	string	Required	Card expiration date in MMYY format	"1225" (December 2025)
`cvv`	string	Required	Card security code (CVV/CVC)	"123"
`cardHolder`	string	Required	Cardholder name	"John Doe"

Option 2: Previously Tokenized Card (Alternative to card details)

Parameter	Type	Required	Description	Example
`token`	string/number	Required	Previously generated payment token (use instead of card details)	4459079401220002

Billing Address Parameters

addressBilling object - Required for new card transactions:

Property	Type	Required	Description	Example
`name`	string	Required	Full name of cardholder	"John Doe"
`firstName`	string	Optional	First name (alternative to full name)	"John"
`lastName`	string	Optional	Last name (alternative to full name)	"Doe"
`street`	string	Required	Street address line 1	"123 Main St"
`street2`	string	Optional	Street address line 2 (apartment, suite, etc.)	"Apt 4B"
`city`	string	Required	City name	"Anytown"
`state`	string	Required	State or province code (2-letter US state code)	"CA", "NY"
`zipcode`	string/number	Required	ZIP or postal code	"12345", 12345
`country`	string	Required	Country code (2-letter ISO code)	"US", "CA"
`phone`	string	Optional	Phone number	"555-1234"

Shipping Address Parameters

addressShipping object - Optional, same structure as addressBilling:

Parameter	Type	Required	Description
`addressShipping`	object	Optional	Shipping address object with same properties as addressBilling. Can be empty object {} if not applicable.

Source Data

Parameter	Type	Required	Description
`sourceData`	object	Optional	Additional metadata or source information for the transaction. Can be empty object {} if not used.

Payment API

The Cloud Payment API supports multiple transaction types for card-not-present payment processing.

Supported Transaction Types

Sale - Complete sale transaction with immediate charge
Auth - Authorization only (funds held, not captured)
Capture - Capture previously authorized amount
Void - Cancel/void a sale or return transaction
Return - Refund a previous transaction
Token - Tokenize card without charging
Delete - Cancel/delete an authorization before capture

Sale Transaction

Complete a sale transaction with immediate charge to the card.

Required Parameters

transactionType: "sale"
amount: Transaction amount
Card details OR token
addressBilling: Billing address object

Example Request

// Request
{
  "requestType": "payment",
  "actionType": "process",
  "transactionType": "sale",
  "amount": "10.00",
  "cardHolder": "John Doe",
  "invoiceNumber": "INV-12345",
  "email": "john@example.com",
  "customerIp": "192.168.1.100",
  "getToken": true,
  "addressBilling": {
    "name": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zipcode": "12345",
    "country": "US",
    "phone": "555-1234"
  },
  "cardNumber": "4111111111111111",
  "cardExpDate": "1225",
  "cvv": "123",
  "addressShipping": {},
  "sourceData": {}
}

// Response
{
  "status": "ok",
  "timestamp": 1761087920,
  "version": "1.0.0",
  "paymentStatus": "APPROVED",
  "message": "APPROVAL",
  "authCode": "112892",
  "referenceNumber": "211025O2C-EE3A17F7-70FD-4061-AEA3-30F60DEFBA68",
  "transactionType": "SALE",
  "amount": "10.00",
  "token": "4034762327081111",
  "tokenResponse": "SUCCESS",
  "cardType": "CREDITCARD",
  "cardNumber": "1111",
  "cardHolder": "John Doe"
}

Auth Transaction (Authorization Only)

Authorize a transaction without capturing funds. Funds are held but not charged until captured.

Required Parameters

transactionType: "auth"
amount: Amount to authorize
Card details OR token
addressBilling: Billing address object

Example Request

// Request
{
  "requestType": "payment",
  "actionType": "process",
  "transactionType": "auth",
  "amount": "100.00",
  "cardHolder": "John Doe",
  "invoiceNumber": "INV-67890",
  "customerIp": "192.168.1.100",
  "addressBilling": {
    "name": "John Doe",
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zipcode": "12345",
    "country": "US"
  },
  "cardNumber": "4111111111111111",
  "cardExpDate": "1225",
  "cvv": "123",
  "addressShipping": {},
  "sourceData": {}
}

// Response
{
  "status": "ok",
  "paymentStatus": "APPROVED",
  "message": "APPROVAL",
  "authCode": "AUTH123",
  "referenceNumber": "211025O2C-AUTH-12345",
  "transactionType": "AUTH",
  "amount": "100.00"
}

Capture Transaction

Capture a previously authorized transaction. Can be full or partial capture.

Required Parameters

transactionType: "capture"
referenceNumber: Reference from original auth transaction
amount: Optional - Amount to capture (defaults to full authorized amount)

Example Request

// Request - Full Capture
{
  "requestType": "payment",
  "actionType": "process",
  "transactionType": "capture",
  "referenceNumber": "211025O2C-AUTH-12345"
}

// Request - Partial Capture
{
  "requestType": "payment",
  "actionType": "process",
  "transactionType": "capture",
  "referenceNumber": "211025O2C-AUTH-12345",
  "amount": "50.00"
}

// Response
{
  "status": "ok",
  "paymentStatus": "APPROVED",
  "message": "CAPTURED",
  "referenceNumber": "211025O2C-CAPTURE-67890",
  "transactionType": "CAPTURE",
  "amount": "50.00"
}

Void Transaction

Cancel/void a sale or return transaction. Must be done on the same day as the original transaction.

Required Parameters

transactionType: "void"
referenceNumber: Reference from original transaction to void

Example Request

// Request
{
  "requestType": "payment",
  "actionType": "process",
  "transactionType": "void",
  "referenceNumber": "281025C45-9C229B8E-DD67-4434-AC25-293C9DD037AF"
}

// Response
{
  "status": "ok",
  "paymentStatus": "APPROVED",
  "message": "VOIDED",
  "transactionType": "VOID",
  "referenceNumber": "281025C45-9C229B8E-DD67-4434-AC25-293C9DD037AF"
}

Return Transaction (Refund)

Refund a previous transaction. Can be full or partial refund.

Required Parameters

transactionType: "return"
referenceNumber: Reference from original transaction
amount: Optional - Amount to refund (defaults to full transaction amount)

Example Request

// Request - Full Refund
{
  "requestType": "payment",
  "actionType": "process",
  "transactionType": "return",
  "referenceNumber": "211025O2C-SALE-12345"
}

// Request - Partial Refund
{
  "requestType": "payment",
  "actionType": "process",
  "transactionType": "return",
  "referenceNumber": "211025O2C-SALE-12345",
  "amount": "25.00"
}

// Response
{
  "status": "ok",
  "paymentStatus": "APPROVED",
  "message": "REFUNDED",
  "transactionType": "RETURN",
  "amount": "25.00",
  "referenceNumber": "211025O2C-RETURN-99999"
}

Token Transaction (Tokenization Only)

Tokenize a card without processing a charge. Use for storing payment methods for future transactions.

Required Parameters

transactionType: "token"
amount: "0.00" (must be zero)
Card details (cannot use existing token)
addressBilling: Billing address object

Example Request

// Request
{
  "requestType": "payment",
  "actionType": "process",
  "transactionType": "token",
  "amount": "0.00",
  "cardHolder": "Jacob Voorhies",
  "invoiceNumber": "1001-1761682959",
  "addressBilling": {
    "name": "Jacob Voorhies",
    "firstName": "Jacob",
    "lastName": "Voorhies",
    "street": "4132 Beechwood Drive",
    "city": "Baltimore",
    "state": "MD",
    "zipcode": 21201,
    "country": "US",
    "phone": "555-1001"
  },
  "cardNumber": "4000000000000002",
  "cardExpDate": "1226",
  "cvv": "123",
  "customerIp": "192.168.1.100",
  "addressShipping": {},
  "sourceData": {}
}

// Response
{
  "status": "ok",
  "transactionType": "token",
  "amount": "0.00",
  "cardHolder": "Jacob Voorhies",
  "invoiceNumber": "1001-1761682959",
  "token": "4459079401220002",
  "tokenResponse": "SUCCESS"
}

Using Previously Tokenized Card

Once you have a token, you can use it for future transactions without passing card details:

// Request
{
  "requestType": "payment",
  "actionType": "process",
  "transactionType": "sale",
  "amount": "144.11",
  "invoiceNumber": "1019-1761683024",
  "token": 4459079401220002,
  "customerIp": "192.168.1.100",
  "addressBilling": {},
  "addressShipping": {},
  "sourceData": {}
}

// Response
{
  "status": "ok",
  "paymentStatus": "APPROVED",
  "transactionType": "sale",
  "amount": "144.11",
  "invoiceNumber": "1019-1761683024",
  "authCode": "AUTH321",
  "referenceNumber": "281025O2D-52A80546-89CF-436B-A89B-A832FDD9FF38",
  "token": 4459079401220002
}

Delete Transaction (Cancel Authorization)

Cancel/delete an authorization before it is captured. This permanently removes the authorization.

Required Parameters

transactionType: "delete"
referenceNumber: Reference from original auth transaction

Example Request

// Request
{
  "requestType": "payment",
  "actionType": "process",
  "transactionType": "delete",
  "referenceNumber": "281025C45-9C229B8E-DD67-4434-AC25-293C9DD037AF"
}

// Response
{
  "status": "ok",
  "paymentStatus": "APPROVED",
  "message": "DELETED",
  "transactionType": "DELETE",
  "referenceNumber": "281025C45-9C229B8E-DD67-4434-AC25-293C9DD037AF"
}

Response Format

Standard Response Fields

All Cloud Payment API responses include these base fields:

Field	Type	Always Present	Description	Example Values
`status`	string	✓ Yes	Overall request status	"ok", "error"
`timestamp`	integer	✓ Yes	Response timestamp (Unix timestamp in seconds)	1761087920
`version`	string	✓ Yes	API version	"1.0.0"

Transaction Response Fields

Fields returned for successful payment transactions:

Field	Type	Description	Example
`paymentStatus`	string	Payment transaction result	"APPROVED", "DECLINED", "ERROR"
`message`	string	Response message or description	"APPROVAL", "Insufficient Funds"
`referenceNumber`	string	Unique transaction identifier - SAVE THIS for capture/void/return operations	"211025O2C-EE3A17F7-..."
`transactionId`	string	Internal transaction identifier	"MH169X56_AC3556463BD8957C_..."
`transactionType`	string	Type of transaction performed	"SALE", "AUTH", "CAPTURE", "VOID", "RETURN"
`transactionTime`	string	Transaction timestamp (UTC)	"2025-10-21 19:05:20 UTC"
`authCode`	string	Authorization code from payment processor	"112892", "AUTH456"
`resultCode`	string	Result code ("0" indicates success)	"0", "100", "200"

Amount Fields

Field	Type	Description	Example
`amount`	string	Final transaction amount processed	"10.00"
`amountRequested`	string	Originally requested amount	"10.00"
`amountPurchase`	string	Purchase amount (before fees/surcharges)	"10.00"
`amountTip`	string	Tip amount	"0.00"
`amountFee`	string	Processing fee amount	"0.00"
`amountSurcharge`	string	Surcharge amount	"0.00"
`balanceDue`	string	Remaining balance (for partial auth)	"0.00"
`salesTax`	string	Sales tax amount (if applicable)	"0.85"

Card Information Fields

Field	Type	Description	Example
`cardType`	string	Card brand or type	"VISA", "MASTERCARD", "AMEX", "DISCOVER", "CREDITCARD"
`cardNumber`	string	Last 4 digits of card number	"1111", "1234"
`cardEntry`	string	Card entry method	"MANUAL", "CHIP", "SWIPE", "CONTACTLESS"
`cardHolder`	string	Cardholder name	"John Doe"
`tenderType`	string	Tender/payment type	"CREDIT", "DEBIT"

Tokenization Fields

Returned when getToken=true in request:

Field	Type	Description	Example
`token`	string	Tokenized card number for future transactions	"4034762327081111"
`tokenResponse`	string	Token generation status	"SUCCESS", "FAILURE"
`getToken`	string	Token request flag from request	"Y", "N"

Verification Fields

Address and CVV verification results:

Field	Type	Description	Example
`avs`	object	Address Verification System result	{ "value": "ZIP5_MATCH_ADDRESS_MISMATCH", "description": "..." }
`avs.value`	string	AVS code	"ZIP5_MATCH_ADDRESS_MATCH", "ZIP5_MATCH_ADDRESS_MISMATCH"
`avs.description`	string	Human-readable AVS result description	"5-digit ZIP matches; address does not match."
`cvv`	object	CVV verification result	{ "value": "CVV_MATCH", "description": "..." }
`cvv.value`	string	CVV verification code	"CVV_MATCH", "CVV_MISMATCH", "CVV_NOT_PROCESSED"
`cvv.description`	string	Human-readable CVV result description	"CVV2/CVC2 match."

Additional Fields

Field	Type	Description	Example
`invoiceNumber`	string	Invoice number from request (if provided)	"INV-12345"
`paymentModule`	string	Payment processor/gateway used	"converge", "authorize", "cardconnect"
`issuerResponse`	string	Response from card issuer	""
`isPartialAuth`	boolean	Whether partial authorization occurred	false, true
`transactionCurrency`	string	Transaction currency code	"USD", "CAD"
`partnerAppId`	string	Partner application identifier (if applicable)	"APP123"

Example Success Response

{
  "status": "ok",
  "timestamp": 1761087920,
  "version": "1.0.0",
  "paymentStatus": "APPROVED",
  "message": "APPROVAL",
  "authCode": "112892",
  "referenceNumber": "211025O2C-EE3A17F7-70FD-4061-AEA3-30F60DEFBA68",
  "transactionType": "SALE",
  "tenderType": "CREDIT",
  "amount": "10.00",
  "invoiceNumber": "INV-12345",
  "resultCode": "0",
  "cardType": "CREDITCARD",
  "cardNumber": "1111",
  "cardEntry": "MANUAL",
  "cardHolder": "John Doe",
  "paymentModule": "converge",
  "token": "4034762327081111",
  "tokenResponse": "SUCCESS",
  "transactionTime": "2025-10-21 19:05:20 UTC",
  "avs": {
    "value": "ZIP5_MATCH_ADDRESS_MISMATCH",
    "description": "5-digit ZIP matches; address does not match."
  },
  "cvv": {
    "value": "CVV_MATCH",
    "description": "CVV2/CVC2 match."
  },
  "amountRequested": "10.00",
  "balanceDue": "0.00",
  "isPartialAuth": false,
  "transactionId": "MH169X56_AC3556463BD8957C_5RVH_L93D"
}

Error Handling

Common Error Responses

Invalid Signature

{
  "status": "error",
  "timestamp": 1234567890000,
  "version": "1.0.0",
  "message": "Invalid signature"
}

Request Timestamp Expired

{
  "status": "error",
  "timestamp": 1234567890000,
  "version": "1.0.0",
  "message": "Request timestamp expired"
}

Authentication Error

{
  "status": "error",
  "timestamp": 1234567890000,
  "version": "1.0.0",
  "message": "Authentication error: [details]"
}

Cloud Payment API Tester

API URL

API Key

API Secret

Request Body (JSON)

Response

No request sent yet

Cloud Payment API Integration Example

JavaScript/Node.js Example

const crypto = require('crypto');
const fetch = require('node-fetch');

class VelaPayCloudClient {
    constructor(apiKey, apiSecret, baseUrl = 'https://api.velapay.net/v1/') {
        this.apiKey = apiKey;
        this.apiSecret = apiSecret;
        this.baseUrl = baseUrl;
    }

    generateSignature(timestamp, body) {
        const message = timestamp + body;
        return crypto
            .createHmac('sha256', this.apiSecret)
            .update(message)
            .digest('hex');
    }

    async makeRequest(payload) {
        const timestamp = Math.floor(Date.now() / 1000).toString();
        const body = JSON.stringify(payload);
        const signature = this.generateSignature(timestamp, body);

        const response = await fetch(this.baseUrl, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'X-API-Key': this.apiKey,
                'X-Timestamp': timestamp,
                'X-Signature': signature
            },
            body: body
        });

        return response.json();
    }

    async processSale(cardData, amount, billingAddress, options = {}) {
        const paymentRequest = {
            requestType: 'payment',
            actionType: 'process',
            transactionType: 'sale',
            amount: amount.toString(),
            cardNumber: cardData.cardNumber,
            cardExpDate: cardData.expDate,
            cvv: cardData.cvv,
            cardHolder: cardData.cardHolder,
            addressBilling: billingAddress,
            email: options.email,
            customerIp: options.customerIp,
            invoiceNumber: options.invoiceNumber,
            getToken: options.tokenize || false
        };

        return this.makeRequest(paymentRequest);
    }

    async captureTransaction(referenceNumber, amount) {
        const captureRequest = {
            requestType: 'payment',
            actionType: 'process',
            transactionType: 'capture',
            referenceNumber: referenceNumber,
            amount: amount.toString()
        };

        return this.makeRequest(captureRequest);
    }

    async voidTransaction(referenceNumber) {
        const voidRequest = {
            requestType: 'payment',
            actionType: 'process',
            transactionType: 'void',
            referenceNumber: referenceNumber
        };

        return this.makeRequest(voidRequest);
    }
}

// Usage Example
async function processOnlineOrder() {
    const client = new VelaPayCloudClient(
        'your-api-key',
        'your-api-secret'
    );

    const cardData = {
        cardNumber: '4111111111111111',
        expDate: '1225',
        cvv: '123',
        cardHolder: 'John Doe'
    };

    const billingAddress = {
        name: 'John Doe',
        street: '123 Main St',
        city: 'Anytown',
        state: 'CA',
        zipcode: '12345',
        country: 'US',
        phone: '555-1234'
    };

    try {
        const result = await client.processSale(
            cardData,
            125.00,
            billingAddress,
            {
                email: 'customer@example.com',
                customerIp: '192.168.1.100',
                invoiceNumber: 'WEB-ORDER-12345',
                tokenize: true
            }
        );

        if (result.status === 'ok' && result.paymentStatus === 'APPROVED') {
            console.log('Payment approved!');
            console.log('Reference Number:', result.referenceNumber);
            console.log('Auth Code:', result.authCode);

            if (result.token) {
                console.log('Card tokenized:', result.token);
            }
        } else {
            console.error('Payment declined:', result.message);
        }
    } catch (error) {
        console.error('Error processing payment:', error);
    }
}

processOnlineOrder();

VelaPay Manager API

Introduction

Getting Started

Prerequisites

For Local Terminal API:

For Cloud Payment API:

Quick Decision Guide

Use Local Terminal API when you need to:

Use Cloud Payment API when you need to:

Best Practices

General Best Practices

Authentication Best Practices

Cloud Payment API Best Practices

Support

Contact Information

Getting API Credentials

For Cloud Payment API:

For Local Terminal API:

Local Terminal API

Payment Processing

Terminal Control

Hardware Integration

Configuration

Getting Started

Prerequisites

Server Configuration

Authentication

Local Requests

Remote Requests - HMAC-SHA256 Signature

Signature Calculation Example (JavaScript)

Request/Response Format

Base Request Structure

Base Response Structure

Supported Payment Types

API Request Types

system

device

payment

dialog

print

msr

System API

Request Parameters

POST Restart Application

POST Capture Screenshot

POST Get Log List

Device API

GET Get Device Info

Payment API

Transaction Types

Tender Types

Payment Request Parameters

Tip Prompt Parameters

Payment Response Fields

Batch Settlement Response Fields

POST Process Sale

POST Batch Settlement

Dialog API

Dialog Types

Common Dialog Parameters

Input Dialog Specific Parameters

Button Dialog Specific Parameters

Signature Dialog Specific Parameters

POST Button Dialog

Select Option

POST Input Dialog

Enter Amount

POST Signature Dialog

APPROVED

Print API

Print Types

Common Print Parameters

Image Print Parameters

Template Print Parameters

Print Item Types

Text Item

Barcode Item

QR Code Item

Line Item

Feed Item