Skip to content

API Testing Tools ​

While Postman is our recommended tool, you can test BITXpay APIs using various other tools. This guide covers popular alternatives with Ed25519 signature generation examples.

Two things every helper below gets right

  1. The signed path is the full request path including /api/v1 (POST/api/v1/payment_links…), never just /payment_links.
  2. The private key is used exactly as the dashboard issued it: Ed25519:<base64 PKCS#8 DER>. Tools that need PEM get the base64 part wrapped in -----BEGIN PRIVATE KEY----- / -----END PRIVATE KEY-----.

cURL ​

cURL is a command-line tool available on most systems. Here's how to test with cURL using a helper script.

Setup Script ​

Create a bash script bitxpay-curl.sh:

bash
#!/bin/bash

# Configuration
API_KEY="${MERCHANT_API_KEY:?set MERCHANT_API_KEY}"            # btxm_xxxxxxxxxxxx
PRIVATE_KEY="${MERCHANT_PRIVATE_KEY:?set MERCHANT_PRIVATE_KEY}" # Ed25519:MC4CAQAw... as issued
HOST="https://sandboxapi.bitxpay.com"
PREFIX="/api/v1"

# Get request details
METHOD=$1
ENDPOINT=$2      # e.g. /payment_links  (the /api/v1 prefix is added below)
BODY=${3:-}

# Generate timestamp
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

# Create message to sign: METHOD + FULL PATH + TIMESTAMP + BODY
MESSAGE="${METHOD}${PREFIX}${ENDPOINT}${TIMESTAMP}${BODY}"

# Wrap the issued key as PEM for OpenSSL and sign (Ed25519, OpenSSL >= 3).
# pkeyutl -rawin needs real files, so use a temporary directory.
WORK=$(mktemp -d); trap 'rm -rf "$WORK"' EXIT
printf -- '-----BEGIN PRIVATE KEY-----\n%s\n-----END PRIVATE KEY-----\n' "${PRIVATE_KEY#Ed25519:}" > "$WORK/key.pem"
printf '%s' "$MESSAGE" > "$WORK/message"
SIGNATURE=$(openssl pkeyutl -sign -inkey "$WORK/key.pem" -rawin -in "$WORK/message" | base64 -w 0)

# Make request
if [ -z "$BODY" ]; then
  curl -X "$METHOD" "${HOST}${PREFIX}${ENDPOINT}" \
    -H "X-API-Key: $API_KEY" \
    -H "X-API-Signature: $SIGNATURE" \
    -H "X-API-Timestamp: $TIMESTAMP" \
    -H "Accept: application/json"
else
  curl -X "$METHOD" "${HOST}${PREFIX}${ENDPOINT}" \
    -H "X-API-Key: $API_KEY" \
    -H "X-API-Signature: $SIGNATURE" \
    -H "X-API-Timestamp: $TIMESTAMP" \
    -H "Content-Type: application/json" \
    -d "$BODY"
fi

Usage ​

bash
chmod +x bitxpay-curl.sh
export MERCHANT_API_KEY=btxm_xxxxxxxxxxxx
export MERCHANT_PRIVATE_KEY='Ed25519:MC4CAQAw...'

# Create payment link
./bitxpay-curl.sh POST /payment_links '{"payment_name":"Test Payment","amount":10,"currency":"USDT","success_url":"https://example.com/success","cancel_url":"https://example.com/cancel"}'

# Get payment details
./bitxpay-curl.sh GET /payment_links/payment-id-here

Node.js Helper for cURL ​

If your OpenSSL CLI doesn't support Ed25519, use this Node.js helper:

javascript
#!/usr/bin/env node
const crypto = require('crypto');
const { execSync } = require('child_process');

const apiKey = process.env.MERCHANT_API_KEY;                    // btxm_xxxxxxxxxxxx
const issued = process.env.MERCHANT_PRIVATE_KEY;                // Ed25519:MC4CAQAw...
const privateKey = crypto.createPrivateKey({
  key: Buffer.from(issued.slice('Ed25519:'.length), 'base64'),
  format: 'der',
  type: 'pkcs8',
});
const host = 'https://sandboxapi.bitxpay.com';
const prefix = '/api/v1';

const [method, endpoint, body = ''] = process.argv.slice(2);  // endpoint e.g. /payment_links
const path = prefix + endpoint;                                 // the FULL path is signed
const timestamp = new Date().toISOString();
const message = `${method}${path}${timestamp}${body}`;

const signature = crypto.sign(null, Buffer.from(message, 'utf8'), privateKey).toString('base64');

const curlCmd = body
  ? `curl -X ${method} "${host}${path}" -H "X-API-Key: ${apiKey}" -H "X-API-Signature: ${signature}" -H "X-API-Timestamp: ${timestamp}" -H "Content-Type: application/json" -d '${body}'`
  : `curl -X ${method} "${host}${path}" -H "X-API-Key: ${apiKey}" -H "X-API-Signature: ${signature}" -H "X-API-Timestamp: ${timestamp}"`;

console.log(execSync(curlCmd).toString());

Save as bitxpay-request.js and use:

bash
chmod +x bitxpay-request.js
./bitxpay-request.js POST /payment_links '{"payment_name":"Test Payment","amount":10,"currency":"USDT",...}'

Insomnia ​

Insomnia is a modern REST client with a clean interface.

Setup ​

  1. Install Insomnia from insomnia.rest
  2. Create a new Request Collection
  3. Set up Environment Variables

Environment Variables ​

Create an environment with:

json
{
  "base_url": "https://sandboxapi.bitxpay.com/api/v1",
  "api_key": "your_api_key",
  "private_key": "Ed25519:MC4CAQAwBQYDK2VwBCIEI..."
}

Pre-Request Script ​

Insomnia supports plugins. Install the insomnia-plugin-request-hooks plugin:

  1. Go to Preferences → Plugins
  2. Search for "request-hooks"
  3. Install the plugin

Create a hook file .insomnia/hooks.js:

javascript
const crypto = require('crypto');

module.exports.requestHooks = [
  (context) => {
    const { request } = context;
    const issued = context.environment.private_key;          // Ed25519:... as issued
    const apiKey = context.environment.api_key;
    const privateKey = crypto.createPrivateKey({
      key: Buffer.from(issued.slice('Ed25519:'.length), 'base64'),
      format: 'der',
      type: 'pkcs8',
    });
    
    const method = request.getMethod();
    const url = new URL(request.getUrl());
    const path = url.pathname;                                // full path incl. /api/v1 (base_url contains it)
    const timestamp = new Date().toISOString();
    const body = request.getBodyText() || '';
    
    const message = `${method}${path}${timestamp}${body}`;
    
    const signature = crypto.sign(null, Buffer.from(message, 'utf8'), privateKey).toString('base64');
    
    request.setHeader('X-API-Key', apiKey);
    request.setHeader('X-API-Signature', signature);
    request.setHeader('X-API-Timestamp', timestamp);
  }
];

Manual Signature (Alternative) ​

If you prefer not to use plugins, generate signatures externally and paste them:

  1. Use the Node.js script above to generate signature
  2. Copy the signature value
  3. Manually add headers in Insomnia

HTTPie ​

HTTPie is a user-friendly command-line HTTP client.

Installation ​

bash
# macOS
brew install httpie

# Ubuntu/Debian
apt install httpie

# Python pip
pip install httpie

Usage with Helper Script ​

Create bitxpay-http.sh:

bash
#!/bin/bash

API_KEY="${MERCHANT_API_KEY:?}"              # btxm_xxxxxxxxxxxx
PRIVATE_KEY="${MERCHANT_PRIVATE_KEY:?}"      # Ed25519:MC4CAQAw... as issued
HOST="https://sandboxapi.bitxpay.com"
PREFIX="/api/v1"

METHOD=$1
ENDPOINT=$2
BODY=${3:-}

TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
MESSAGE="${METHOD}${PREFIX}${ENDPOINT}${TIMESTAMP}${BODY}"   # full path is signed

WORK=$(mktemp -d); trap 'rm -rf "$WORK"' EXIT
printf -- '-----BEGIN PRIVATE KEY-----\n%s\n-----END PRIVATE KEY-----\n' "${PRIVATE_KEY#Ed25519:}" > "$WORK/key.pem"
printf '%s' "$MESSAGE" > "$WORK/message"
SIGNATURE=$(openssl pkeyutl -sign -inkey "$WORK/key.pem" -rawin -in "$WORK/message" | base64 -w 0)

if [ -z "$BODY" ]; then
  http "$METHOD" "${HOST}${PREFIX}${ENDPOINT}" \
    "X-API-Key:$API_KEY" \
    "X-API-Signature:$SIGNATURE" \
    "X-API-Timestamp:$TIMESTAMP"
else
  printf '%s' "$BODY" | http "$METHOD" "${HOST}${PREFIX}${ENDPOINT}" \
    "X-API-Key:$API_KEY" \
    "X-API-Signature:$SIGNATURE" \
    "X-API-Timestamp:$TIMESTAMP"
fi

Example ​

bash
chmod +x bitxpay-http.sh

# Create payment
./bitxpay-http.sh POST /payment_links '{"payment_name":"Test Payment","amount":10,"currency":"USDT",...}'

REST Client (VS Code Extension) ​

REST Client is a VS Code extension that lets you test APIs directly in your editor.

Installation ​

  1. Open VS Code
  2. Go to Extensions (Ctrl+Shift+X)
  3. Search for "REST Client"
  4. Install by Huachao Mao

Setup ​

Create a file bitxpay-requests.http:

http
### Variables
@baseUrl = https://sandboxapi.bitxpay.com/api/v1
@apiKey = your_api_key_here

### Create Payment Link
# @name createPayment
POST {{baseUrl}}/payment_links
X-API-Key: {{apiKey}}
X-API-Signature: {{$processEnv SIGNATURE}}
X-API-Timestamp: {{$processEnv TIMESTAMP}}
Content-Type: application/json

{
  "payment_name": "Test Payment",
  "amount": 10,
  "currency": "USDT",
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel"
}

### Get Payment Link by ID
GET {{baseUrl}}/payment_links/{{createPayment.response.body.id}}
X-API-Key: {{apiKey}}
X-API-Signature: {{$processEnv SIGNATURE}}
X-API-Timestamp: {{$processEnv TIMESTAMP}}

Note: You'll need to generate SIGNATURE and TIMESTAMP environment variables externally using the Node.js script.


Thunder Client (VS Code Extension) ​

Thunder Client is a lightweight REST client for VS Code.

Installation ​

  1. Open VS Code
  2. Install "Thunder Client" extension
  3. Open Thunder Client from the sidebar

Setup ​

  1. Create Environment

    • Click "Env" tab
    • Add variables: base_url, api_key, private_key
  2. Pre-Request Script

    Thunder Client supports JavaScript in pre-request scripts:

    javascript
    const crypto = require('crypto');
    
    const apiKey = tc.getVar('api_key');
    const issued = tc.getVar('private_key');                 // Ed25519:... as issued
    const privateKey = crypto.createPrivateKey({
      key: Buffer.from(issued.slice('Ed25519:'.length), 'base64'),
      format: 'der',
      type: 'pkcs8',
    });
    const method = tc.request.method;
    const url = new URL(tc.request.url);
    const path = url.pathname;                                // full path incl. /api/v1
    const timestamp = new Date().toISOString();
    const body = tc.request.body || '';
    
    const message = `${method}${path}${timestamp}${body}`;
    
    const signature = crypto.sign(null, Buffer.from(message, 'utf8'), privateKey).toString('base64');
    
    tc.setVar('signature', signature);
    tc.setVar('timestamp', timestamp);
  3. Add Headers

    • X-API-Key:
    • X-API-Signature:
    • X-API-Timestamp:

Python Requests ​

For Python developers, here's a reusable class:

python
import os
import json
import base64
from datetime import datetime, timezone
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.backends import default_backend
import requests

class BITXpayClient:
    def __init__(self, api_key, private_key, host='https://sandboxapi.bitxpay.com', prefix='/api/v1'):
        self.api_key = api_key              # btxm_xxxxxxxxxxxx
        self.host = host
        self.prefix = prefix
        # private_key is the "Ed25519:<base64 PKCS#8 DER>" string shown in the dashboard
        der = base64.b64decode(private_key[len('Ed25519:'):])
        self.private_key = serialization.load_der_private_key(der, password=None, backend=default_backend())
    
    def _generate_signature(self, method, path, timestamp, body=''):
        # path is the FULL request path, e.g. /api/v1/payment_links
        message = f"{method}{path}{timestamp}{body}"
        
        signature = self.private_key.sign(
            message.encode('utf-8')
        )
        
        return base64.b64encode(signature).decode('utf-8')
    
    def request(self, method, endpoint, data=None):
        path = self.prefix + endpoint
        timestamp = datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
        body = json.dumps(data) if data else ''
        
        signature = self._generate_signature(method, path, timestamp, body)
        
        headers = {
            'X-API-Key': self.api_key,
            'X-API-Signature': signature,
            'X-API-Timestamp': timestamp,
            'Content-Type': 'application/json'
        }
        
        url = f"{self.host}{path}"
        
        response = requests.request(
            method,
            url,
            headers=headers,
            data=body if body else None
        )
        
        return response.json()
    
    def create_payment_link(self, payment_data):
        return self.request('POST', '/payment_links', payment_data)
    
    def get_payment_link(self, payment_id):
        return self.request('GET', f'/payment_links/{payment_id}')
    
    def delete_payment_link(self, payment_id):
        return self.request('DELETE', f'/payment_links/{payment_id}')

# Usage
client = BITXpayClient(
    api_key=os.environ['MERCHANT_API_KEY'],
    private_key=os.environ['MERCHANT_PRIVATE_KEY']   # 'Ed25519:MC4CAQAw...'
)

payment = client.create_payment_link({
    'payment_name': 'Test Payment',
    'amount': 10,
    'currency': 'USDT',
    'success_url': 'https://example.com/success',
    'cancel_url': 'https://example.com/cancel'
})

print(payment)

PHP Example ​

For PHP developers:

php
<?php

class BITXpayClient {
    private $apiKey;
    private $privateKey;
    
    private $host = 'https://sandboxapi.bitxpay.com';
    private $prefix = '/api/v1';
    
    public function __construct($apiKey, $issuedPrivateKey) {
        $this->apiKey = $apiKey;   // btxm_xxxxxxxxxxxx
        // $issuedPrivateKey is the "Ed25519:<base64 PKCS#8 DER>" string from the dashboard.
        // Ed25519 signing needs the sodium extension; convert PKCS#8 DER -> 32-byte seed -> sodium secret key.
        $der = base64_decode(substr($issuedPrivateKey, strlen('Ed25519:')));
        $seed = substr($der, -32);                       // last 32 bytes of the PKCS#8 structure
        $this->privateKey = sodium_crypto_sign_secretkey(sodium_crypto_sign_seed_keypair($seed));
    }
    
    private function generateSignature($method, $path, $timestamp, $body = '') {
        // $path is the FULL request path, e.g. /api/v1/payment_links
        $message = $method . $path . $timestamp . $body;
        
        $signature = sodium_crypto_sign_detached($message, $this->privateKey);
        
        return base64_encode($signature);
    }
    
    public function request($method, $endpoint, $data = null) {
        $path = $this->prefix . $endpoint;
        $timestamp = gmdate('Y-m-d\TH:i:s\Z');
        $body = $data ? json_encode($data) : '';
        
        $signature = $this->generateSignature($method, $path, $timestamp, $body);
        
        $headers = [
            'X-API-Key: ' . $this->apiKey,
            'X-API-Signature: ' . $signature,
            'X-API-Timestamp: ' . $timestamp,
            'Content-Type: application/json'
        ];
        
        $ch = curl_init($this->host . $path);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        
        if ($body) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
        }
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
    
    public function createPaymentLink($paymentData) {
        return $this->request('POST', '/payment_links', $paymentData);
    }
}

// Usage
$client = new BITXpayClient(
    getenv('MERCHANT_API_KEY'),
    getenv('MERCHANT_PRIVATE_KEY')   // 'Ed25519:MC4CAQAw...'
);

$payment = $client->createPaymentLink([
    'payment_name' => 'Test Payment',
    'amount' => 10,
    'currency' => 'USDT',
    'success_url' => 'https://example.com/success',
    'cancel_url' => 'https://example.com/cancel'
]);

print_r($payment);

Comparison Table ​

ToolDifficultyAutomationBest For
PostmanEasyExcellentBeginners, Teams
InsomniaEasyGoodDevelopers
cURLMediumExcellentCI/CD, Scripts
HTTPieEasyGoodCommand-line fans
REST ClientEasyGoodVS Code users
Thunder ClientEasyGoodLightweight testing
PythonMediumExcellentPython projects
PHPMediumExcellentPHP projects

Next Steps ​

Support ​

Need help with a specific tool?