接口概览 - MC Platform Open API

SpeedPay 会通过 Webhook 将异步业务结果推送到商户在 API KEY 中配置的 HTTPS 回调地址。回调地址由商户提供，不是固定的平台接口路径。

通用请求

项目	说明
方法	`POST`
地址	商户在 SpeedPay 商户平台 API KEY 中配置的 HTTPS 回调地址
内容类型	`application/json`
超时时间	5 秒
签名 Header	`Authorization`

Authorization 的值为 SpeedPay 使用平台私钥对完整 JSON 请求体签名后的结果。商户需要使用 SpeedPay 公钥验签，验签失败时不得处理业务数据。

Go 回调验签

回调使用 SpeedPay 平台私钥签名，商户使用 SpeedPay 公钥验签。算法为 SHA256withRSA（RSA PKCS#1 v1.5 + SHA-256），Authorization 是标准 Base64 编码的签名值。验签原文必须是接收到的完整原始 JSON 字节。不要先解析再序列化，否则字段顺序、空格、换行或转义变化会导致验签失败。 回调验签函数

package signature

import (
	"crypto"
	"crypto/rsa"
	"crypto/sha256"
	"crypto/x509"
	"encoding/base64"
	"encoding/pem"
	"fmt"
)

func VerifySHA256RSA(body []byte, signatureBase64 string, publicKeyPEM []byte) error {
	block, _ := pem.Decode(publicKeyPEM)
	if block == nil {
		return fmt.Errorf("decode public key PEM")
	}

	publicKey, err := parseRSAPublicKey(block.Bytes)
	if err != nil {
		return err
	}
	signature, err := base64.StdEncoding.DecodeString(signatureBase64)
	if err != nil {
		return fmt.Errorf("decode Base64 signature: %w", err)
	}

	digest := sha256.Sum256(body)
	if err := rsa.VerifyPKCS1v15(publicKey, crypto.SHA256, digest[:], signature); err != nil {
		return fmt.Errorf("verify signature: %w", err)
	}
	return nil
}

func parseRSAPublicKey(der []byte) (*rsa.PublicKey, error) {
	parsedKey, err := x509.ParsePKIXPublicKey(der)
	if err == nil {
		publicKey, ok := parsedKey.(*rsa.PublicKey)
		if !ok {
			return nil, fmt.Errorf("public key is not RSA")
		}
		return publicKey, nil
	}

	publicKey, pkcs1Err := x509.ParsePKCS1PublicKey(der)
	if pkcs1Err != nil {
		return nil, fmt.Errorf("parse RSA public key: PKIX: %v; PKCS#1: %w", err, pkcs1Err)
	}
	return publicKey, nil
}

Webhook Handler 示例

func callbackHandler(speedPayPublicKeyPEM []byte) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		rawBody, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20))
		if err != nil {
			http.Error(w, "invalid request body", http.StatusBadRequest)
			return
		}

		authorization := r.Header.Get("Authorization")
		if authorization == "" {
			http.Error(w, "missing signature", http.StatusUnauthorized)
			return
		}
		if err := signature.VerifySHA256RSA(rawBody, authorization, speedPayPublicKeyPEM); err != nil {
			http.Error(w, "invalid signature", http.StatusUnauthorized)
			return
		}

		// 验签通过后再解析 rawBody，并执行幂等处理。
		w.Header().Set("Content-Type", "application/json")
		_, _ = w.Write([]byte(`{"code":0,"msg":"success"}`))
	}
}

生产代码应在启动时加载 SpeedPay 公钥，不要在日志中输出完整签名或敏感请求体。PEM 解析失败、Base64 解码失败或验签失败时，必须停止处理业务数据。

成功应答

商户处理成功后返回以下 JSON：

{
  "code": 0,
  "msg": "success"
}

code 必须为数字 0。非 0、网络错误或超时会被记录为回调失败。

Visa 回调类型

`api_name`	说明	详情
`pr_card_activation_result_push`	Visa 开卡/申请结果	Visa 回调
`transaction_advice`	Visa 交易通知	Visa 回调
`change_advice`	Visa 卡状态变更	Visa 回调
`express_advice`	Visa 物流信息变更	Visa 回调
`mobile_advice`	Visa 手机号变更	Visa 回调
`apply_edit_advice`	Visa 申请资料变更	Visa 回调

JCB 回调类型

`api_name`	说明	详情
`jcb_card_apply_status`	JCB 申请单状态变化	JCB 回调
`jcb_card_status_change`	JCB 卡状态变更	JCB 回调
`jcb_card_transaction_3ds`	JCB 3DS 验证码	JCB 回调
`jcb_card_block_transaction`	JCB 链上充值	JCB 回调
`jcb_card_transaction`	JCB 卡片消费	JCB 回调
`jcb_card_block_express`	JCB 物流信息变更	JCB 回调
`jcb_card_to_card`	JCB 卡对卡转账结果	JCB 回调
`jcb_mobile_advice`	JCB 手机号变更	JCB 回调
`jcb_email_advice`	JCB 邮箱变更	JCB 回调
`jcb_card_no_advice`	JCB 卡号变更	JCB 回调
`jcb_apply_edit_advice`	JCB 申请资料变更	JCB 回调

处理要求

要求	说明
先验签后入库	使用 SpeedPay 公钥对完整 JSON 请求体进行验签
幂等处理	根据 `api_name`、业务流水号、交易 ID、卡号等字段去重
快速响应	建议验签后先落库或入队列，再异步处理重业务逻辑
保留原文	建议保存原始请求体、签名、处理结果和错误信息，便于排查

​通用请求

​Go 回调验签

​成功应答

​Visa 回调类型

​JCB 回调类型

​处理要求