PayPal订单详情API获取交易信息

大家好，我们又见面了啊~本文《PayPal订单详情API获取交易与买家信息》的内容中将会涉及到等等。如果你正在学习文章相关知识，欢迎关注我，以后会给大家带来更多文章相关文章，希望我们能一起进步！下面就开始本文的正式内容~

本文旨在指导开发者如何通过PayPal的订单详情API（Order Details API）获取完整的交易数据和付款人（Payer）信息，特别是当PayPal仅返回Payer ID时。教程将详细阐述如何利用订单ID（而非Payer ID）构建API请求、处理响应，并提取包括电子邮件地址在内的关键付款人详情，附带Java示例代码和最佳实践。

在PayPal交易流程中，有时回调URL或某些场景下仅提供PayerID。然而，PayerID主要用于标识一个付款人，它本身并非一个唯一的交易标识符，因此PayPal并没有直接通过PayerID获取特定交易所有详细信息的API。要获取包括客户电子邮件地址、姓名及其他交易详情在内的完整数据，我们需要依赖于交易的唯一标识符，即order_id（订单ID）或payment_id（支付ID），并通过PayPal的订单详情API进行查询。

1. 理解Payer ID与订单ID的区别

• Payer ID: 标识一个PayPal账户的唯一ID。一个付款人可以进行多笔交易，因此PayerID无法唯一确定一笔特定的交易。
• Order ID (或 Payment ID): 标识一笔PayPal订单或支付的唯一ID。这是获取特定交易详情的关键。通常在创建PayPal订单或授权支付时，PayPal会返回一个order_id或payment_id。开发者需要在支付流程中妥善保存此ID，以便后续查询。

当您在回调URL中只收到PayerID时，这通常意味着支付授权已完成，但您需要使用之前在支付发起阶段获得的order_id来查询该笔授权对应的订单详情。

2. 通过PayPal订单详情API获取交易数据

PayPal的订单详情API是获取交易完整信息的官方途径。该API允许您通过order_id检索特定订单的所有相关数据，包括付款人信息、购买单位详情、交易状态等。

2.1 认证与授权

所有PayPal API请求都需要进行认证。通常，这意味着您需要获取一个有效的Bearer Access Token。这个Token通过OAuth 2.0流程从PayPal的认证服务获取，并需要在每个API请求的Authorization头中传递。

// 假设您已有一个获取Access Token的方法
public String getAccessToken() {
    // 实现获取PayPal Access Token的逻辑
    // 通常涉及向PayPal /v1/oauth2/token 端点发送POST请求
    // 使用您的Client ID和Secret进行基本认证
    return "YOUR_PAYPAL_ACCESS_TOKEN"; // 示例
}

2.2 构建API请求

获取订单详情的API端点是：/v2/checkout/orders/{id}。您需要将{id}替换为实际的order_id。

以下是一个使用Java HttpClient发送GET请求获取订单详情的示例：

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.databind.ObjectMapper; // 假设使用Jackson进行JSON解析
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;

public class PayPalService {

    private final HttpClient httpClient;
    private final ObjectMapper objectMapper;
    private static final String BASE_URL = "https://api-m.paypal.com"; // 或沙箱环境 "https://api-m.sandbox.paypal.com"
    private static final String ORDER_DETAILS_PATH = "/v2/checkout/orders/{id}";

    public PayPalService() {
        this.httpClient = HttpClient.newHttpClient();
        this.objectMapper = new ObjectMapper();
    }

    /**
     * 获取PayPal订单的详细信息。
     * @param orderId PayPal订单的唯一ID。
     * @return 包含订单详情的DTO对象。
     * @throws IOException 如果发生I/O错误。
     * @throws InterruptedException 如果线程在等待时被中断。
     */
    public PayPalOrderResponseDTO getOrderDetails(String orderId) throws IOException, InterruptedException {
        String accessToken = getAccessToken(); // 获取Access Token

        // 构建API请求URL
        String requestUrl = BASE_URL + ORDER_DETAILS_PATH.replace("{id}", orderId);

        // 创建HTTP请求
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(requestUrl))
                .header("Authorization", "Bearer " + accessToken)
                .GET()
                .build();

        // 发送请求并获取响应
        HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

        // 检查响应状态码
        if (response.statusCode() != 200) {
            System.err.println("Error fetching order details: " + response.body());
            throw new IOException("Failed to fetch order details. Status code: " + response.statusCode());
        }

        // 解析JSON响应到DTO对象
        return objectMapper.readValue(response.body(), PayPalOrderResponseDTO.class);
    }

    // 假设的getAccessToken方法，需要您根据实际认证流程实现
    private String getAccessToken() {
        // 在实际应用中，这里会调用PayPal的OAuth2 /v1/oauth2/token 端点获取
        // 为简化示例，此处返回一个占位符
        return "YOUR_PAYPAL_ACCESS_TOKEN";
    }

    // ... PayPalOrderResponseDTO 及相关嵌套DTO的定义将在下一节给出
}

2.3 处理API响应与提取Payer信息

PayPal订单详情API的响应是一个包含丰富数据的JSON对象。其中，付款人信息位于payer字段下。

响应DTO结构示例 (Java Record 类型):

// PayPalOrderResponseDTO.java
public record PayPalOrderResponseDTO(
    @JsonProperty("create_time") String creationTime,
    @JsonProperty("update_time") String updateTime,
    String id,
    @JsonProperty("purchase_units") List<PayPalPurchaseUnit> payPalPurchaseUnits,
    List<PayPalLink> links,
    @JsonProperty("payment_source") PayPalPaymentSource paymentSource,
    PayPalOrderIntent intent,
    @JsonProperty("payer") PayPalPayer payPalPayer, // 付款人信息
    PayPalOrderStatus status
) {}

// PayPalPayer.java
public record PayPalPayer(
    @JsonProperty("email_address") String emailAddress,
    @JsonProperty("payer_id") String payerId, // 注意：这里会返回Payer ID
    PayPalName name,
    PayPalPhone phone,
    @JsonProperty("birth_date") String birthDate,
    PayPalAddress address
) {}

// PayPalName.java
public record PayPalName(
    @JsonProperty("given_name") String givenName,
    String surname
) {}

// 其他辅助DTO，根据实际需要定义
// PayPalPurchaseUnit.java
public record PayPalPurchaseUnit(
    String referenceId,
    @JsonProperty("shipping") PayPalShipping shipping,
    @JsonProperty("payments") PayPalPayments payments
) {}

// PayPalShipping.java
public record PayPalShipping(
    @JsonProperty("name") PayPalName name,
    @JsonProperty("address") PayPalAddress address
) {}

// PayPalAddress.java
public record PayPalAddress(
    @JsonProperty("address_line_1") String addressLine1,
    @JsonProperty("admin_area_2") String adminArea2,
    @JsonProperty("admin_area_1") String adminArea1,
    @JsonProperty("postal_code") String postalCode,
    @JsonProperty("country_code") String countryCode
) {}

// PayPalPayments.java (可能包含授权或捕获信息)
public record PayPalPayments(
    List<PayPalAuthorization> authorizations,
    List<PayPalCapture> captures
) {}

// PayPalAuthorization.java / PayPalCapture.java 等根据实际响应结构定义
// ... (为简洁起见，此处省略了所有嵌套DTO的完整定义，但实际应用中应完整映射)

通过上述PayPalOrderResponseDTO，您可以轻松访问payPalPayer字段，进而获取emailAddress、givenName、surname、payerId等付款人详细信息。

示例：提取付款人信息

public void processOrderDetails(String orderId) {
    try {
        PayPalOrderResponseDTO orderDetails = getOrderDetails(orderId);

        // 获取付款人信息
        PayPalPayer payer = orderDetails.payPalPayer();
        if (payer != null) {
            System.out.println("Payer Email: " + payer.emailAddress());
            if (payer.name() != null) {
                System.out.println("Payer Name: " + payer.name().givenName() + " " + payer.name().surname());
            }
            System.out.println("Payer ID (from order details): " + payer.payerId());
            // 更多付款人信息，如地址、电话等
        }

        // 获取其他交易详情
        System.out.println("Order ID: " + orderDetails.id());
        System.out.println("Order Status: " + orderDetails.status());
        // 遍历 purchase_units 获取商品或金额详情
        if (orderDetails.payPalPurchaseUnits() != null && !orderDetails.payPalPurchaseUnits().isEmpty()) {
            orderDetails.payPalPurchaseUnits().forEach(unit -> {
                // 处理每个购买单位的详情
            });
        }

    } catch (IOException | InterruptedException e) {
        System.err.println("Error processing order: " + e.getMessage());
        // 适当的错误处理
    }
}

3. 注意事项与最佳实践

• 订单ID的来源: 确保您在支付发起阶段（例如，调用/v2/checkout/orders创建订单时）正确地捕获并存储了PayPal返回的order_id。这个order_id是后续查询订单详情的关键。
• 安全管理Access Token: Access Token是敏感凭证，应妥善保管。避免将其硬编码在代码中，并确保在服务器端安全地获取和刷新。
• 错误处理: 在实际应用中，务必对API请求的响应进行错误处理。检查HTTP状态码，并解析PayPal返回的错误信息，以便诊断和解决问题。
• 幂等性: 如果您需要多次尝试获取订单详情，确保您的系统能够处理幂等性。虽然GET请求通常是幂等的，但在某些操作（如捕获支付）中，需要特别注意。
• 沙箱环境测试: 在部署到生产环境之前，务必在PayPal的沙箱环境中充分测试您的集成。
• 跨语言适用性: 尽管示例代码是Java，但这种通过订单ID调用PayPal订单详情API的逻辑适用于任何支持HTTP请求和JSON解析的编程语言（如Python, Node.js, PHP, C#等）。核心在于构建正确的URL、设置认证头和解析JSON响应。

总结

当PayPal仅返回PayerID而您需要完整的交易和付款人详情时，正确的做法是利用您在支付流程初期获得的order_id（或payment_id），调用PayPal的订单详情API（/v2/checkout/orders/{id}）。通过此API，您可以获取一个包含所有必要信息的JSON响应，其中包括付款人的电子邮件地址、姓名等。遵循本文提供的指导和示例，您可以有效地集成PayPal API，并安全、准确地获取所需的交易数据。

到这里，我们也就讲完了《PayPal订单详情API获取交易信息》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！