Spring Boot应用集成2Checkout支付网关技术问询

核心集成步骤 #

1. 前期准备 #

• 注册2Checkout商家账号，获取API密钥、商家ID，明确使用环境（沙盒/生产）
• 在2Checkout后台配置Webhook回调地址，开启支付成功、订单更新等关键事件的通知

2. 引入依赖 #

Maven项目在pom.xml中添加官方SDK依赖：

<dependency>
    <groupId>com.2co</groupId>
    <artifactId>2checkout-java</artifactId>
    <version>4.0.0</version> <!-- 请确认最新版本 -->
</dependency>

Gradle项目添加：

implementation 'com.2co:2checkout-java:4.0.0'

3. 初始化客户端 #

创建配置类统一初始化2Checkout客户端，区分环境：

import com.twocheckout.Twocheckout;
import org.springframework.context.annotation.Configuration;

@Configuration
public class TwoCheckoutConfig {
    public TwoCheckoutConfig() {
        Twocheckout.apiKey = "你的API密钥";
        Twocheckout.sellerId = "你的商家ID";
        Twocheckout.mode = "sandbox"; // 生产环境改为"production"
        Twocheckout.verifySSL = true; // 生产环境建议开启SSL验证
    }
}

4. 生成支付链接 #

编写服务类处理订单创建，生成支付跳转链接：

import com.twocheckout.TwocheckoutException;
import com.twocheckout.model.Charge;
import org.springframework.stereotype.Service;
import java.util.HashMap;
import java.util.Map;

@Service
public class PaymentService {
    public String generatePaymentUrl(String orderId, Double total, String currency, String customerEmail) throws TwocheckoutException {
        Map<String, Object> chargeParams = new HashMap<>();
        chargeParams.put("merchantOrderId", orderId);
        chargeParams.put("currency", currency);
        chargeParams.put("total", total);
        
        Map<String, Object> billingInfo = new HashMap<>();
        billingInfo.put("email", customerEmail);
        chargeParams.put("billingDetails", billingInfo);

        Charge charge = Charge.create(chargeParams);
        return charge.get("redirectUrl");
    }
}

5. 处理Webhook回调 #

创建Controller接收支付结果通知，重点做签名验证：

import com.twocheckout.Twocheckout;
import com.twocheckout.util.SignatureUtils;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import javax.servlet.http.HttpServletRequest;
import java.util.Map;

@RestController
@RequestMapping("/webhook")
public class PaymentWebhookController {
    @PostMapping("/2checkout")
    public String handlePaymentNotify(@RequestBody Map<String, Object> payload, HttpServletRequest request) {
        // 验证签名，防止伪造请求
        String signature = request.getHeader("X-2Checkout-Signature");
        boolean isValid = SignatureUtils.verifySignature(payload, signature, Twocheckout.apiKey);
        
        if (!isValid) {
            return "Invalid signature";
        }

        // 业务处理：更新订单状态、发送通知等
        String orderStatus = (String) payload.get("status");
        String merchantOrderId = (String) payload.get("merchantOrderId");
        // 此处添加你的订单状态更新逻辑
        
        return "Success";
    }
}

6. 测试与上线 #

• 用沙盒环境测试信用卡（如4111111111111111，过期日期填未来年月，CVV123）完成支付流程验证
• 上线前切换生产环境配置，确认API密钥、商家ID、Webhook地址均为生产环境值

实用经验提示 #

• Webhook的签名验证必须做，这是防止恶意请求的核心手段
• 沙盒与生产环境的配置完全隔离，不要混用密钥和ID
• 处理回调时要做幂等性校验，避免同一订单重复处理
• 若官方SDK功能有限，可直接调用2Checkout REST API，参数格式参考官方接口说明

内容的提问来源于stack exchange，提问作者OrkhanGG