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
- The signed path is the full request path including
/api/v1(POST/api/v1/payment_links…), never just/payment_links. - 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:
#!/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"
fiUsage
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-hereNode.js Helper for cURL
If your OpenSSL CLI doesn't support Ed25519, use this Node.js helper:
#!/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:
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
- Install Insomnia from insomnia.rest
- Create a new Request Collection
- Set up Environment Variables
Environment Variables
Create an environment with:
{
"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:
- Go to Preferences → Plugins
- Search for "request-hooks"
- Install the plugin
Create a hook file .insomnia/hooks.js:
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:
- Use the Node.js script above to generate signature
- Copy the signature value
- Manually add headers in Insomnia
HTTPie
HTTPie is a user-friendly command-line HTTP client.
Installation
# macOS
brew install httpie
# Ubuntu/Debian
apt install httpie
# Python pip
pip install httpieUsage with Helper Script
Create bitxpay-http.sh:
#!/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"
fiExample
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
- Open VS Code
- Go to Extensions (Ctrl+Shift+X)
- Search for "REST Client"
- Install by Huachao Mao
Setup
Create a file bitxpay-requests.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
- Open VS Code
- Install "Thunder Client" extension
- Open Thunder Client from the sidebar
Setup
Create Environment
- Click "Env" tab
- Add variables:
base_url,api_key,private_key
Pre-Request Script
Thunder Client supports JavaScript in pre-request scripts:
javascriptconst 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);Add Headers
X-API-Key:X-API-Signature:X-API-Timestamp:
Python Requests
For Python developers, here's a reusable class:
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
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
| Tool | Difficulty | Automation | Best For |
|---|---|---|---|
| Postman | Easy | Excellent | Beginners, Teams |
| Insomnia | Easy | Good | Developers |
| cURL | Medium | Excellent | CI/CD, Scripts |
| HTTPie | Easy | Good | Command-line fans |
| REST Client | Easy | Good | VS Code users |
| Thunder Client | Easy | Good | Lightweight testing |
| Python | Medium | Excellent | Python projects |
| PHP | Medium | Excellent | PHP projects |
Next Steps
- Postman Setup - Detailed Postman guide
- Troubleshooting - Common issues
- API Reference - Explore endpoints
Support
Need help with a specific tool?
- Email: api-support@bitxpay.com
- Documentation: https://docs.bitxpay.com/