商户 API 接入文档

import * as crypto from 'node:crypto'

type ArthaPayRequest = {
  headers: Record<string, string>
  body: string
}

export function buildArthaPayRequest(
  apiKey: string,
  businessPayload: unknown,
  platformPublicKeyPem: string,
  merchantPrivateKeyPem: string,
): ArthaPayRequest {
  // 业务参数先序列化为 JSON；明文不直接参与签名。
  const plainJson = JSON.stringify(businessPayload)
  // 每次请求（包括重试）都生成新的 AES Key 和 IV。
  const aesKey = crypto.randomBytes(32)
  const iv = crypto.randomBytes(12)

  const cipher = crypto.createCipheriv('aes-256-gcm', aesKey, iv)
  const encrypted = Buffer.concat([
    cipher.update(plainJson, 'utf8'),
    cipher.final(),
  ])
  // 将密文与 128 位 GCM 认证标签拼接，再 Base64 编码。
  const cipherText = Buffer.concat([encrypted, cipher.getAuthTag()]).toString('base64')

  // 使用平台 RSA 公钥和 PKCS#1 v1.5 加密 AES Key 原始字节，作为 X-Encrypt-Key。
  const encryptKey = crypto.publicEncrypt(
    {
      key: platformPublicKeyPem,
      padding: crypto.constants.RSA_PKCS1_PADDING,
    },
    aesKey,
  ).toString('base64')

  // 推荐秒级 Unix 时间戳；nonce 每次请求均须不同。
  const timestamp = Math.floor(Date.now() / 1000).toString()
  const nonce = crypto.randomBytes(16).toString('hex')
  // 按顺序直接拼接四段原始字符串，不添加分隔符或空格；时间戳须与请求头完全一致。
  // 不要把业务明文、整个信封、X-IV 或 X-Encrypt-Key 加入签名原文。
  const signPayload = apiKey + timestamp + nonce + cipherText
  // 使用商户 RSA 私钥对 UTF-8 签名原文执行 SHA256withRSA，并将结果 Base64 编码。
  const sign = crypto.sign(
    'RSA-SHA256',
    Buffer.from(signPayload, 'utf8'),
    merchantPrivateKeyPem,
  ).toString('base64')

  return {
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': apiKey,
      'X-Timestamp': timestamp,
      'X-Nonce': nonce,
      'X-Encrypt-Key': encryptKey,
      'X-IV': iv.toString('base64'),
      'X-Sign': sign,
    },
    body: JSON.stringify({ cipherText }),
  }
}

package arthapay

import (
	"crypto"
	"crypto/aes"
	"crypto/cipher"
	"crypto/rand"
	"crypto/rsa"
	"crypto/sha256"
	"crypto/x509"
	"encoding/base64"
	"encoding/hex"
	"encoding/json"
	"encoding/pem"
	"errors"
	"strconv"
	"time"
)

type RequestData struct {
	Headers map[string]string
	Body    string
}

func BuildArthaPayRequest(
	apiKey string,
	businessPayload any,
	platformPublicKeyPEM string,
	merchantPrivateKeyPEM string,
) (*RequestData, error) {
	// 业务参数序列化为 JSON；查单可传入 map[string]any{}，生成 {}。
	plainJSON, err := json.Marshal(businessPayload)
	if err != nil {
		return nil, err
	}

	// 每次请求（包括重试）生成新的 32 字节 AES Key 和 12 字节 IV。
	aesKey := make([]byte, 32)
	if _, err = rand.Read(aesKey); err != nil {
		return nil, err
	}
	iv := make([]byte, 12)
	if _, err = rand.Read(iv); err != nil {
		return nil, err
	}

	// AES-GCM 输出为密文与 128 位认证标签的拼接，再进行 Base64 编码。
	cipherText, err := aesGcmEncryptToBase64(plainJSON, aesKey, iv)
	if err != nil {
		return nil, err
	}

	// 使用平台 RSA 公钥及 PKCS#1 v1.5 加密 AES Key 原始字节。
	publicKey, err := readPublicKey(platformPublicKeyPEM)
	if err != nil {
		return nil, err
	}
	encryptKeyBytes, err := rsa.EncryptPKCS1v15(rand.Reader, publicKey, aesKey)
	if err != nil {
		return nil, err
	}
	encryptKey := base64.StdEncoding.EncodeToString(encryptKeyBytes)

	// 使用秒级 Unix 时间戳，每次请求生成新的 nonce。
	timestamp := strconv.FormatInt(time.Now().Unix(), 10)
	nonceBytes := make([]byte, 16)
	if _, err = rand.Read(nonceBytes); err != nil {
		return nil, err
	}
	nonce := hex.EncodeToString(nonceBytes)

	// 按顺序直接拼接四段原始字符串，不加分隔符；时间戳须与请求头完全一致。
	// 业务明文、整个信封、X-IV 和 X-Encrypt-Key 不参与签名。
	signPayload := apiKey + timestamp + nonce + cipherText
	privateKey, err := readPrivateKey(merchantPrivateKeyPEM)
	if err != nil {
		return nil, err
	}
	// 使用商户 RSA 私钥执行 SHA256withRSA，再将签名字节 Base64 编码。
	hashed := sha256.Sum256([]byte(signPayload))
	signBytes, err := rsa.SignPKCS1v15(rand.Reader, privateKey, crypto.SHA256, hashed[:])
	if err != nil {
		return nil, err
	}
	sign := base64.StdEncoding.EncodeToString(signBytes)

	body, err := json.Marshal(map[string]string{"cipherText": cipherText})
	if err != nil {
		return nil, err
	}

	return &RequestData{
		Headers: map[string]string{
			"Content-Type":  "application/json",
			"X-Api-Key":     apiKey,
			"X-Timestamp":   timestamp,
			"X-Nonce":       nonce,
			"X-Encrypt-Key": encryptKey,
			"X-IV":          base64.StdEncoding.EncodeToString(iv),
			"X-Sign":        sign,
		},
		Body: string(body),
	}, nil
}

func aesGcmEncryptToBase64(plainJSON, aesKey, iv []byte) (string, error) {
	block, err := aes.NewCipher(aesKey)
	if err != nil {
		return "", err
	}
	gcm, err := cipher.NewGCM(block)
	if err != nil {
		return "", err
	}
	sealed := gcm.Seal(nil, iv, plainJSON, nil)
	return base64.StdEncoding.EncodeToString(sealed), nil
}

// 公钥使用 X.509 SubjectPublicKeyInfo PEM（BEGIN PUBLIC KEY）。
func readPublicKey(pemStr string) (*rsa.PublicKey, error) {
	block, _ := pem.Decode([]byte(pemStr))
	if block == nil {
		return nil, errors.New("invalid public key PEM")
	}
	parsed, err := x509.ParsePKIXPublicKey(block.Bytes)
	if err != nil {
		return nil, err
	}
	publicKey, ok := parsed.(*rsa.PublicKey)
	if !ok {
		return nil, errors.New("not an RSA public key")
	}
	return publicKey, nil
}

// 私钥使用 PKCS#8 PEM（BEGIN PRIVATE KEY）。
func readPrivateKey(pemStr string) (*rsa.PrivateKey, error) {
	block, _ := pem.Decode([]byte(pemStr))
	if block == nil {
		return nil, errors.New("invalid private key PEM")
	}
	parsed, err := x509.ParsePKCS8PrivateKey(block.Bytes)
	if err != nil {
		return nil, err
	}
	privateKey, ok := parsed.(*rsa.PrivateKey)
	if !ok {
		return nil, errors.New("not an RSA private key")
	}
	return privateKey, nil
}

<?php
// 需要 PHP 7.3+，并启用 OpenSSL 扩展。
function buildArthaPayRequest(
    string $apiKey,
    $businessPayload,
    string $platformPublicKeyPem,
    string $merchantPrivateKeyPem
): array {
    // 业务参数先序列化为 JSON；查单时使用 (object) []，确保明文为 {}。
    $plainJson = json_encode($businessPayload, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);

    // 每次请求（包括重试）生成新的 32 字节 AES Key 和 12 字节 IV。
    $aesKey = random_bytes(32);
    $iv = random_bytes(12);

    // 使用 AES-256-GCM 加密；认证标签长度为 16 字节（128 位）。
    $tag = '';
    $encrypted = openssl_encrypt(
        $plainJson,
        'aes-256-gcm',
        $aesKey,
        OPENSSL_RAW_DATA,
        $iv,
        $tag,
        '',
        16
    );
    if ($encrypted === false || strlen($tag) !== 16) {
        throw new RuntimeException('AES-GCM encryption failed');
    }

    // 将密文与认证标签拼接，再 Base64 编码，作为请求体 cipherText。
    $cipherText = base64_encode($encrypted . $tag);

    // 使用平台 RSA 公钥及 PKCS#1 v1.5 加密 AES Key 原始字节。
    $encryptedKey = '';
    if (!openssl_public_encrypt($aesKey, $encryptedKey, $platformPublicKeyPem, OPENSSL_PKCS1_PADDING)) {
        throw new RuntimeException('RSA key encryption failed');
    }
    $encryptKey = base64_encode($encryptedKey);

    // 使用秒级 Unix 时间戳，每次请求生成新的 nonce。
    $timestamp = (string) time();
    $nonce = bin2hex(random_bytes(16));

    // 按顺序直接拼接四段原始字符串，不加分隔符；时间戳须与请求头完全一致。
    // 业务明文、整个信封、X-IV 和 X-Encrypt-Key 不参与签名。
    $signPayload = $apiKey . $timestamp . $nonce . $cipherText;

    // 使用商户 RSA 私钥执行 SHA256withRSA，再将签名字节 Base64 编码。
    $signature = '';
    if (!openssl_sign($signPayload, $signature, $merchantPrivateKeyPem, OPENSSL_ALGO_SHA256)) {
        throw new RuntimeException('RSA signing failed');
    }
    $sign = base64_encode($signature);

    return [
        'headers' => [
            'Content-Type' => 'application/json',
            'X-Api-Key' => $apiKey,
            'X-Timestamp' => $timestamp,
            'X-Nonce' => $nonce,
            'X-Encrypt-Key' => $encryptKey,
            'X-IV' => base64_encode($iv),
            'X-Sign' => $sign,
        ],
        'body' => json_encode(['cipherText' => $cipherText], JSON_THROW_ON_ERROR),
    ];
}

import com.fasterxml.jackson.databind.ObjectMapper;

import javax.crypto.Cipher;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.KeyFactory;
import java.security.PrivateKey;
import java.security.PublicKey;
import java.security.SecureRandom;
import java.security.Signature;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;
import java.time.Instant;
import java.util.Base64;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.UUID;

public final class ArthaPayMerchantCrypto {
    private static final ObjectMapper MAPPER = new ObjectMapper();
    private static final SecureRandom RANDOM = new SecureRandom();
    private static final int GCM_TAG_LENGTH_BIT = 128;

    public static RequestData buildRequest(
            String apiKey,
            Object businessPayload,
            String platformPublicKeyPem,
            String merchantPrivateKeyPem
    ) throws Exception {
        // 业务参数先序列化为 JSON；明文不直接参与签名。
        String plainJson = MAPPER.writeValueAsString(businessPayload);
        // 每次请求（包括重试）都生成新的 AES Key 和 IV。
        byte[] aesKey = randomBytes(32);
        byte[] iv = randomBytes(12);

        // Java 的 GCM doFinal 输出已包含 128 位认证标签，整体进行 Base64 编码。
        String cipherText = aesGcmEncryptToBase64(plainJson, aesKey, iv);
        // 使用平台 RSA 公钥和 PKCS#1 v1.5 加密 AES Key 原始字节，作为 X-Encrypt-Key。
        String encryptKey = rsaEncryptToBase64(aesKey, readPublicKey(platformPublicKeyPem));
        // 推荐秒级 Unix 时间戳；nonce 每次请求均须不同。
        String timestamp = String.valueOf(Instant.now().getEpochSecond());
        String nonce = UUID.randomUUID().toString().replace("-", "");
        // 按顺序直接拼接四段原始字符串，不添加分隔符或空格；时间戳须与请求头完全一致。
        // 不要把业务明文、整个信封、X-IV 或 X-Encrypt-Key 加入签名原文。
        String signPayload = apiKey + timestamp + nonce + cipherText;
        // 使用商户 RSA 私钥对 UTF-8 签名原文执行 SHA256withRSA，并将结果 Base64 编码。
        String sign = rsaSignToBase64(signPayload, readPrivateKey(merchantPrivateKeyPem));

        Map<String, String> headers = new LinkedHashMap<>();
        headers.put("Content-Type", "application/json");
        headers.put("X-Api-Key", apiKey);
        headers.put("X-Timestamp", timestamp);
        headers.put("X-Nonce", nonce);
        headers.put("X-Encrypt-Key", encryptKey);
        headers.put("X-IV", Base64.getEncoder().encodeToString(iv));
        headers.put("X-Sign", sign);

        String body = MAPPER.writeValueAsString(Map.of("cipherText", cipherText));
        return new RequestData(headers, body);
    }

    private static String aesGcmEncryptToBase64(String plainJson, byte[] aesKey, byte[] iv) throws Exception {
        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
        cipher.init(
                Cipher.ENCRYPT_MODE,
                new SecretKeySpec(aesKey, "AES"),
                new GCMParameterSpec(GCM_TAG_LENGTH_BIT, iv)
        );
        return Base64.getEncoder().encodeToString(cipher.doFinal(plainJson.getBytes(StandardCharsets.UTF_8)));
    }

    private static String rsaEncryptToBase64(byte[] plainBytes, PublicKey publicKey) throws Exception {
        Cipher cipher = Cipher.getInstance("RSA/ECB/PKCS1Padding");
        cipher.init(Cipher.ENCRYPT_MODE, publicKey);
        return Base64.getEncoder().encodeToString(cipher.doFinal(plainBytes));
    }

    private static String rsaSignToBase64(String payload, PrivateKey privateKey) throws Exception {
        Signature signature = Signature.getInstance("SHA256withRSA");
        signature.initSign(privateKey);
        signature.update(payload.getBytes(StandardCharsets.UTF_8));
        return Base64.getEncoder().encodeToString(signature.sign());
    }

    // 公钥使用 X.509 SubjectPublicKeyInfo PEM（BEGIN PUBLIC KEY）。
    private static PublicKey readPublicKey(String pem) throws Exception {
        String key = normalizePem(pem, "PUBLIC KEY");
        return KeyFactory.getInstance("RSA").generatePublic(
                new X509EncodedKeySpec(Base64.getDecoder().decode(key))
        );
    }

    // 私钥使用 PKCS#8 PEM（BEGIN PRIVATE KEY）。
    private static PrivateKey readPrivateKey(String pem) throws Exception {
        String key = normalizePem(pem, "PRIVATE KEY");
        return KeyFactory.getInstance("RSA").generatePrivate(
                new PKCS8EncodedKeySpec(Base64.getDecoder().decode(key))
        );
    }

    private static String normalizePem(String pem, String type) {
        return pem
                .replace("-----BEGIN " + type + "-----", "")
                .replace("-----END " + type + "-----", "")
                .replaceAll("\\s", "");
    }

    private static byte[] randomBytes(int length) {
        byte[] bytes = new byte[length];
        RANDOM.nextBytes(bytes);
        return bytes;
    }

    public record RequestData(Map<String, String> headers, String body) {
    }
}