🎫Create Invoice（API）

Basic Flow

Merchant creates an invoice
Pass the pay_url from the invoice response to the customer, who opens the payment page to complete payment.
After Xcash detects the transfer, it sends payment information to the merchant via Webhook callback.

POST https://api.xca.sh/v1/invoice

Function: Generate a pending invoice for the customer, returning the gateway unified invoice number sys_no, payment page, and other information.
Signature Required: Yes.
Request Body Fields

Field

Type

Required

Constraints

Description

out_no

string

Yes

≤32 characters, unique within project

Merchant order number

title

string

Yes

≤32 characters

Customer-visible title

currency

string

Yes

Token or Fiat code, such as ETH/ USD / USDT

Invoice pricing currency

amount

decimal string

Yes

Greater than 0, max 32 digits including 8 decimal places

Amount in invoice pricing currency

duration

int

5~30 (minutes) default 10

Customer payment validity period

methods

object

{"USDT": ["ethereum-mainnet","tron-mainnet"]} structure

Limit customer payment method options; uses all available project methods when empty

redirect_url

string

Redirect URL after successful payment

Business Rules
- If currency is fiat, the payable cryptocurrency amount is automatically calculated based on the exchange rate between cryptocurrency and fiat.
- If currency is cryptocurrency, only that currency is allowed for payment by default.
- Personal edition projects will return TOO_MANY_WAITING when pending invoices ≥ 100; please merge or close old orders.
- If any receiving address for methods chains is missing, returns NO_RECIPIENT_ADDRESS.
methods Format Description
- Represents the payment method combinations available to customers for the current invoice, using JSON object structure.
- Key: Cryptocurrency code (such as USDT, USDC), must be a system-supported currency.
- Value: List of chain codes corresponding to that currency (such as tron-mainnet, ethereum-mainnet), chains must match actual available combinations with the currency. For details, refer to Parameter Codes.

  Example:

示例：

{
  "USDT": ["ethereum-mainnet", "tron-mainnet", "bnbchain-mainnet"],
  "USDC": ["ethereum-mainnet", "tron-mainnet", "bnbchain-mainnet"],
  "ETH": ["ethereum-mainnet"]
}

Examples

import crypto from 'crypto';
import fetch from 'node-fetch';

const APP_ID = "Your-APPID";
const HMAC_KEY = "Your-HMAC-Key";

/**
 * 使用 HMAC-SHA256 生成签名
 * @param {string} key - HMAC 密钥
 * @param {string} message - 要签名的消息
 * @returns {string} - 十六进制格式的签名
 */
function genSignature(key, message) {
    return crypto.createHmac('sha256', key)
                 .update(message)
                 .digest('hex');
}

async function main() {
    const payload = {
        "out_no": `order-${Math.floor(Date.now() / 1000)}`, // 商户单号
        "title": "Test invoice", // 商品标题
        "currency": "USD", // 计价货币
        "amount": "0.01", // 计价货币金额
        "duration": 10, // 支付时间
        "methods": { "USDT": ["bnbchain-mainnet"] }, // 支付方式
        "redirect_url": "https://example.com/" // 支付成功跳转地址
    };

    // crypto.randomUUID() 会生成带连字符的UUID，这里移除它们以匹配 Python 的 uuid.uuid4().hex
    const nonce = crypto.randomUUID().replace(/-/g, '');
    const timestamp = String(Math.floor(Date.now() / 1000));
    const payloadStr = JSON.stringify(payload);

    const message = `${nonce}${timestamp}${payloadStr}`;

    const signature = genSignature(HMAC_KEY, message);

    const headers = {
        "Content-Type": "application/json",
        "XC-Appid": APP_ID,
        "XC-Nonce": nonce,
        "XC-Timestamp": timestamp,
        "XC-Signature": signature,
    };

    try {
        const response = await fetch("https://api.xca.sh/v1/invoice", {
            method: 'POST',
            headers: headers,
            body: payloadStr
        });

        const responseData = await response.json();

        console.log(`HTTP ${response.status}`);
        console.log(JSON.stringify(responseData, null, 2));

    } catch (error) {
        console.error("请求失败:", error);
    }
}

main();

import hashlib
import hmac
import json
import time
import uuid

import httpx

APP_ID = "Your-APPID"
HMAC_KEY = "Your-HMAC-Key"


def gen_signature(key: str, message: str):
    return hmac.new(
        key.encode(),
        message.encode(),
        hashlib.sha256,
    ).hexdigest()


def main():
    payload = {
        "out_no": f"order-{int(time.time())}",  # 商户单号
        "title": "Test invoice",  # 商品标题
        "currency": "USD",  # 计价货币
        "amount": "0.01",  # 计价货币金额
        # "duration": 10,  #可选。 支付时间
        # "methods": {"USDT": ["bnbchain-mainnet"]},  #可选。 支付方式
        # "redirect_url": ""  #可选。 支付成功跳转地址
    }

    nonce = uuid.uuid4().hex
    timestamp = str(int(time.time()))
    payload_str = json.dumps(payload)

    message = f"{nonce}{timestamp}{payload_str}"

    signature = gen_signature(HMAC_KEY, message)

    headers = {
        "Content-Type": "application/json",
        "XC-Appid": APP_ID,
        "XC-Nonce": nonce,
        "XC-Timestamp": timestamp,
        "XC-Signature": signature,
    }

    resp = httpx.post("https://api.xca.sh/v1/invoice", content=payload_str,
                      headers=headers)

    print(f"HTTP {resp.status_code}")
    print(json.dumps(resp.json(), ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()

package main

import (
	"bytes"
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"strconv"
	"strings"
	"time"

	"github.com/google/uuid"
)

const (
	AppID   = "Your-APPID"
	HmacKey = "Your-HMAC-Key"
)

// genSignature 使用 HMAC-SHA256 生成签名
func genSignature(key, message string) string {
	mac := hmac.New(sha256.New, []byte(key))
	mac.Write([]byte(message))
	return hex.EncodeToString(mac.Sum(nil))
}

func main() {
	payload := map[string]interface{}{
		"out_no":       fmt.Sprintf("order-%d", time.Now().Unix()), // 商户单号
		"title":        "Test invoice",                                 // 商品标题
		"currency":     "USD",                                        // 计价货币
		"amount":       "0.01",                                       // 计价货币金额
		"duration":     10,                                           // 支付时间
		"methods":      map[string][]string{"USDT": {"bnbchain-mainnet"}}, // 支付方式
		"redirect_url": "https://example.com",                                           // 支付成功跳转地址
	}

	payloadBytes, err := json.Marshal(payload)
	if err != nil {
		log.Fatalf("无法编码 payload: %v", err)
	}
	payloadStr := string(payloadBytes)

	// 生成 nonce，并移除连字符
	nonce := strings.ReplaceAll(uuid.New().String(), "-", "")
	timestamp := strconv.FormatInt(time.Now().Unix(), 10)

	message := nonce + timestamp + payloadStr

	signature := genSignature(HmacKey, message)

	req, err := http.NewRequest("POST", "https://api.xca.sh/v1/invoice", bytes.NewBuffer(payloadBytes))
	if err != nil {
		log.Fatalf("无法创建请求: %v", err)
	}

	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("XC-Appid", AppID)
	req.Header.Set("XC-Nonce", nonce)
	req.Header.Set("XC-Timestamp", timestamp)
	req.Header.Set("XC-Signature", signature)

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		log.Fatalf("请求失败: %v", err)
	}
	defer resp.Body.Close()

	fmt.Printf("HTTP %d\n", resp.StatusCode)

	// 读取并格式化响应体
	body, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatalf("无法读取响应体: %v", err)
	}

	var prettyJSON bytes.Buffer
	if err := json.Indent(&prettyJSON, body, "", "  "); err != nil {
		// 如果格式化失败，打印原始响应
		log.Printf("无法格式化 JSON 响应: %v", err)
		fmt.Println(string(body))
	} else {
		fmt.Println(prettyJSON.String())
	}
}

<?php

const APP_ID = "Your-APPID";
const HMAC_KEY = "Your-HMAC-Key";

/**
 * 使用 HMAC-SHA256 生成签名
 * @param string $key - HMAC 密钥
 * @param string $message - 要签名的消息
 * @return string - 十六进制格式的签名
 */
function genSignature(string $key, string $message): string
{
    return hash_hmac('sha256', $message, $key);
}

function main()
{
    $payload = [
        "out_no" => "order-" . time(), // 商户单号
        "title" => "Test invoice", // 商品标题
        "currency" => "USD", // 计价货币
        "amount" => "0.01", // 计价货币金额
        "duration" => 10, // 支付时间
        "methods" => ["USDT" => ["bnbchain-mainnet"]], // 支付方式
        "redirect_url" => "https://example.com" // 支付成功跳转地址
    ];

    // 生成一个随机的十六进制字符串作为 nonce
    $nonce = bin2hex(random_bytes(16));
    $timestamp = (string)time();
    // 使用 JSON_UNESCAPED_SLASHES 确保斜杠不被转义，与 Python 行为一致
    $payloadStr = json_encode($payload, JSON_UNESCAPED_SLASHES);

    $message = $nonce . $timestamp . $payloadStr;

    $signature = genSignature(HMAC_KEY, $message);

    $headers = [
        "Content-Type: application/json",
        "XC-Appid: " . APP_ID,
        "XC-Nonce: " . $nonce,
        "XC-Timestamp: " . $timestamp,
        "XC-Signature: " . $signature,
    ];

    $ch = curl_init("https://api.xca.sh/v1/invoice");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payloadStr);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    if (curl_errno($ch)) {
        echo 'cURL 错误: ' . curl_error($ch);
        curl_close($ch);
        return;
    }

    curl_close($ch);

    echo "HTTP " . $httpCode . "\n";
    // 解码后再编码，用于格式化输出
    $responseJson = json_decode($response);
    echo json_encode($responseJson, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) . "\n";
}

main();

Response Field Description

Field

Description

appid

sys_no

System invoice number

out_no

Merchant order number

title

Product title

currency

Pricing currency

amount

Pricing currency amount

methods

Supported payment methods

chain

Blockchain

crypto

Token

crypto_address

Token address

pay_address

Payment address

pay_amount

Payment amount

pay_url

Payment link

expires_at

Payment expiration time

redirect_url

Redirect URL

payment

Network transfer information

status

waiting: pending payment; confirming: awaiting network confirmation; completed: payment complete; expired: expired

PreviousFlow Chart NextRetrieve

Last updated 2 months ago

package main import ( "bytes" "crypto/hmac" "crypto/sha256" "encoding/hex" "encoding/json" "fmt" "io" "log" "net/http" "strconv" "strings" "time" "github.com/google/uuid" ) const ( AppID = "Your-APPID" HmacKey = "Your-HMAC-Key" ) // genSignature 使用 HMAC-SHA256 生成签名 func genSignature(key, message string) string { mac := hmac.New(sha256.New, []byte(key)) mac.Write([]byte(message)) return hex.EncodeToString(mac.Sum(nil)) } func main() { payload := map[string]interface{}{ "out_no": fmt.Sprintf("order-%d", time.Now().Unix()), // 商户单号 "title": "Test invoice", // 商品标题 "currency": "USD", // 计价货币 "amount": "0.01", // 计价货币金额 "duration": 10, // 支付时间 "methods": map[string][]string{"USDT": {"bnbchain-mainnet"}}, // 支付方式 "redirect_url": "https://example.com", // 支付成功跳转地址 } payloadBytes, err := json.Marshal(payload) if err != nil { log.Fatalf("无法编码 payload: %v", err) } payloadStr := string(payloadBytes) // 生成 nonce，并移除连字符 nonce := strings.ReplaceAll(uuid.New().String(), "-", "") timestamp := strconv.FormatInt(time.Now().Unix(), 10) message := nonce + timestamp + payloadStr signature := genSignature(HmacKey, message) req, err := http.NewRequest("POST", "https://api.xca.sh/v1/invoice", bytes.NewBuffer(payloadBytes)) if err != nil { log.Fatalf("无法创建请求: %v", err) } req.Header.Set("Content-Type", "application/json") req.Header.Set("XC-Appid", AppID) req.Header.Set("XC-Nonce", nonce) req.Header.Set("XC-Timestamp", timestamp) req.Header.Set("XC-Signature", signature) client := &http.Client{} resp, err := client.Do(req) if err != nil { log.Fatalf("请求失败: %v", err) } defer resp.Body.Close() fmt.Printf("HTTP %d\n", resp.StatusCode) // 读取并格式化响应体 body, err := io.ReadAll(resp.Body) if err != nil { log.Fatalf("无法读取响应体: %v", err) } var prettyJSON bytes.Buffer if err := json.Indent(&prettyJSON, body, "", " "); err != nil { // 如果格式化失败，打印原始响应 log.Printf("无法格式化 JSON 响应: %v", err) fmt.Println(string(body)) } else { fmt.Println(prettyJSON.String()) } }

<?php const APP_ID = "Your-APPID"; const HMAC_KEY = "Your-HMAC-Key"; /** * 使用 HMAC-SHA256 生成签名 * @param string $key - HMAC 密钥 * @param string $message - 要签名的消息 * @return string - 十六进制格式的签名 */ function genSignature(string $key, string $message): string { return hash_hmac('sha256', $message, $key); } function main() { $payload = [ "out_no" => "order-" . time(), // 商户单号 "title" => "Test invoice", // 商品标题 "currency" => "USD", // 计价货币 "amount" => "0.01", // 计价货币金额 "duration" => 10, // 支付时间 "methods" => ["USDT" => ["bnbchain-mainnet"]], // 支付方式 "redirect_url" => "https://example.com" // 支付成功跳转地址 ]; // 生成一个随机的十六进制字符串作为 nonce $nonce = bin2hex(random_bytes(16)); $timestamp = (string)time(); // 使用 JSON_UNESCAPED_SLASHES 确保斜杠不被转义，与 Python 行为一致 $payloadStr = json_encode($payload, JSON_UNESCAPED_SLASHES); $message = $nonce . $timestamp . $payloadStr; $signature = genSignature(HMAC_KEY, $message); $headers = [ "Content-Type: application/json", "XC-Appid: " . APP_ID, "XC-Nonce: " . $nonce, "XC-Timestamp: " . $timestamp, "XC-Signature: " . $signature, ]; $ch = curl_init("https://api.xca.sh/v1/invoice"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $payloadStr); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); $response = curl_exec($ch); $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); if (curl_errno($ch)) { echo 'cURL 错误: ' . curl_error($ch); curl_close($ch); return; } curl_close($ch); echo "HTTP " . $httpCode . "\n"; // 解码后再编码，用于格式化输出 $responseJson = json_decode($response); echo json_encode($responseJson, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) . "\n"; } main();

Good night

Basic Flow

Examples

Response Field Description