如何在网站中集成 Paymetric.com？

2026-10-24支付老李

结论

Paymetric 可以接入 PHP、Java 或 .NET 网站，但通常不提供注册后就能直接调用的公开支付 API。具体如何接入，要看商户已经开通的 Paymetric 产品、支付渠道和部署模式。接口文档、WSDL、SDK、测试地址和凭据一般由 Paymetric 或支付服务商的实施团队提供。

开始开发前，应先取得当前账户对应的集成包，确认采用托管支付页面、令牌化组件还是服务端 Web Service，不要直接照搬网上的零散示例。三种语言都可以完成接入，主要区别在客户端的实现方式，支付流程大体相同。

接入前需要取得的信息

向 Paymetric 项目联系人、收单机构或支付服务商索取以下资料：

已开通的产品和集成模式。
Sandbox/UAT 与生产环境地址。
API 文档、WSDL、XSD 或官方 SDK。
商户标识、客户端证书、API 凭据和证书密码。
支持的交易类型，例如授权、扣款、撤销和退款。
测试卡号、测试场景和上线认证要求。
Webhook、回调或交易状态查询机制。
PCI DSS 责任范围和生产环境安全要求。

不要根据示例猜测接口地址、SOAP 方法名或字段。不同的商户配置、支付处理机构和 Paymetric 产品，可能对应不同的服务定义。

PHP 示例

下面的代码只演示如何使用 WSDL 创建 SOAP 客户端。Authorize、请求字段和响应字段均为占位名称，必须替换成实际 WSDL 定义的内容。

<?php

$wsdl = getenv('PAYMETRIC_WSDL');
$username = getenv('PAYMETRIC_USERNAME');
$password = getenv('PAYMETRIC_PASSWORD');

$client = new SoapClient($wsdl, [
    'trace' => false,
    'exceptions' => true,
    'cache_wsdl' => WSDL_CACHE_BOTH,
    'connection_timeout' => 20,
]);

$authHeader = new SoapHeader(
    'https://example.invalid/paymetric/security',
    'Authentication',
    [
        'Username' => $username,
        'Password' => $password,
    ]
);

$client->__setSoapHeaders([$authHeader]);

$request = [
    'MerchantReference' => 'ORDER-20260901-001',
    'Amount' => '125.00',
    'Currency' => 'USD',
    'PaymentToken' => 'TOKEN_RETURNED_BY_PAYMETRIC',
];

try {
    // 方法名和参数结构必须以实际 WSDL 为准。
    $response = $client->__soapCall('Authorize', [$request]);

    $transactionId = $response->TransactionId ?? null;
    $status = $response->Status ?? null;

    if ($transactionId === null) {
        throw new RuntimeException('Paymetric response has no transaction ID');
    }

    // 保存 transactionId 和 status，然后按实际状态更新订单。
} catch (SoapFault $e) {
    error_log('Paymetric SOAP request failed: ' . $e->getMessage());

    // 返回通用错误信息，不向浏览器暴露凭据或完整 SOAP 内容。
}

生产环境的认证方式可能是 WS-Security、客户端证书或其他专用机制，不一定使用用户名和密码头。实现时应严格遵循官方安全规范。

Java 示例

取得 WSDL 后，可以使用项目选定的 SOAP 工具生成客户端。较新的 JDK 通常不再内置 wsimport，可改用 Jakarta XML Web Services 或项目指定的代码生成插件。

生成代理类后，调用结构大致如下：

import java.math.BigDecimal;

public final class PaymentService {
    private final PaymetricPort port;

    public PaymentService(PaymetricPort port) {
        this.port = port;
    }

    public PaymentResult authorize(
            String orderId,
            BigDecimal amount,
            String currency,
            String paymentToken) {

        AuthorizeRequest request = new AuthorizeRequest();
        request.setMerchantReference(orderId);
        request.setAmount(amount);
        request.setCurrency(currency);
        request.setPaymentToken(paymentToken);

        // 类型名和方法名由实际 WSDL 生成。
        AuthorizeResponse response = port.authorize(request);

        if (response.getTransactionId() == null) {
            throw new IllegalStateException(
                "Paymetric response has no transaction ID"
            );
        }

        return new PaymentResult(
            response.getTransactionId(),
            response.getStatus()
        );
    }
}

凭据、超时、TLS 证书和 SOAP Header 应放在客户端配置层处理，不要硬编码到业务类中。

.NET 示例

.NET 项目可以根据 WSDL，通过 Visual Studio 的 Connected Services 或 dotnet-svcutil 生成代理代码。下面同样只展示基本结构：

using System;
using System.Threading.Tasks;

public sealed class PaymentService
{
    private readonly PaymetricPortClient _client;

    public PaymentService(PaymetricPortClient client)
    {
        _client = client;
    }

    public async Task<PaymentResult> AuthorizeAsync(
        string orderId,
        decimal amount,
        string currency,
        string paymentToken)
    {
        var request = new AuthorizeRequest
        {
            MerchantReference = orderId,
            Amount = amount,
            Currency = currency,
            PaymentToken = paymentToken
        };

        // 实际方法签名以 WSDL 生成的代理代码为准。
        var response = await _client.AuthorizeAsync(request);

        if (string.IsNullOrWhiteSpace(response.TransactionId))
        {
            throw new InvalidOperationException(
                "Paymetric response has no transaction ID"
            );
        }

        return new PaymentResult(
            response.TransactionId,
            response.Status
        );
    }
}

如果服务要求使用客户端证书，应从受保护的证书存储中加载，不要把 .pfx 文件和密码提交到代码仓库。

订单状态处理

支付请求超时并不等于交易失败。Paymetric 可能已经收到请求，只是网站没有收到响应。如果此时直接重试，可能导致重复授权或重复扣款。

订单状态可以按以下方式处理：

为每笔交易生成唯一的商户订单号或幂等标识。
调用支付接口前，先创建状态为 PENDING 的支付记录。
收到明确的成功响应后，将状态更新为 AUTHORIZED 或 CAPTURED。
收到明确的拒绝响应后，将状态更新为 DECLINED。
遇到超时或网络异常时保留 UNKNOWN 状态，随后通过查询接口核对。
退款和撤销也要保存独立的请求记录与交易引用。
不要仅凭浏览器跳转页面判断支付是否成功。

系统还应保存原始错误代码和必要的响应字段，但必须在日志中屏蔽银行卡号、CVV、访问令牌、密码和证书信息。

安全注意事项

优先使用托管支付字段或令牌化方案，缩小网站直接接触银行卡数据的范围。
不得存储 CVV。
不要把服务端密钥放进浏览器 JavaScript。
支付金额和订单信息都应由后端重新读取并校验，不能信任浏览器提交的金额。
验证回调的签名和时间戳，并处理重复通知。
为创建支付、回调处理和状态查询设置合理的超时时间。
分开管理生产与测试凭据。
不要记录完整的 SOAP 请求，其中可能包含敏感的认证或支付信息。
上线前完成支付服务商要求的认证测试，并确认 PCI DSS 责任边界。

最快落地方案

如果需要尽快完成集成，可以按这个顺序推进：

确认商户已经开通的 Paymetric 产品和对应的处理机构。
获取 UAT 地址、WSDL/SDK、凭据和测试用例。
先完成最小闭环，包括创建会话、取得 token、发起授权和查询状态。
再加入扣款、撤销、退款、超时恢复和回调处理。
完成 UAT 测试及支付服务商认证后，再切换到生产地址和生产凭据。

开发方式最终取决于商户账户对应的接口文档，而不是选择 PHP、Java 还是 .NET。拿到正式的 WSDL、SDK 或托管支付组件说明后，这三种技术栈都能完成稳定接入。