PayPal Hosted Fields集成信用卡支付遇UNPROCESSABLE_ENTITY错误

我正在结账流程中集成带Hosted Fields的信用卡支付，但调用PayPal JS SDK发起的confirm-payment-source请求时，始终收到UNPROCESSABLE_ENTITY错误。

初始化Hosted Field的代码 #

<script src="https://www.paypal.com/sdk/js?components=buttons,hosted-fields&client-id=<%= clientId %>" data-client-token="<%= clientToken %>"></script>
<div id="paypal-button-container" class="paypal-button-container"></div>
<form id="card-form">
    <div id="card-number-field-container"></div>
    <div id="card-expiry-field-container"></div>
    <div id="card-cvv-field-container"></div>
    <button id="submit-button" type="submit">Pay Now</button>
</form>

<script>
let orderId;
paypal.HostedFields.render({
    createOrder: function () {
        orderId = "' . $_SESSION['ppcheckout_order_id'] . '";
        return orderId;
    },
    styles: {
        input: {
            "font-size": "14px",
            "font-family": "Helvetica, Arial, sans-serif",
            "color": "#3a3a3a"
        },
        ":focus": {
            "color": "blue"
        },
        ".valid": {
            "color": "green"
        },
        ".invalid": {
            "color": "red"
        }
    },
    fields: {
        number: {
            selector: "#card-number-field-container",
            placeholder: "Card Number"
        },
        expirationDate: {
            selector: "#card-expiry-field-container",
            placeholder: "MM/YY"
        },
        cvv: {
            selector: "#card-cvv-field-container",
            placeholder: "CVV"
        }
    }
}).then(function (hostedFieldsInstance) {
    document.querySelector("#card-form").addEventListener("submit", function (event) {
        event.preventDefault();

        hostedFieldsInstance.submit({
            //contingencies: ["SCA_WHEN_REQUIRED"],
            cardholderName: "Test Tester",
            billigAddress: {
                streetAddress: "123 Fake St",
                postalCode: "04159",
                region: "Saxonia",
                locality: "Leipzig",
                countryCodeAlpha2: "DE"
            }
        }).then(function(data) {
            console.log(data);
        }).catch(function (err) {
            console.error(err);
        });
    });
});
</script>

错误信息 #

点击“Pay Now”按钮后返回的错误：

{
    "name": "UNPROCESSABLE_ENTITY",
    "details": [
        {
            "field": "/processing_instruction",
            "value": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
            "issue": "UNSUPPORTED_PROCESSING_INSTRUCTION",
            "description": "The specified processing_instruction is not supported for the given payment_source. Please refer to https://developer.paypal.com/docs/api/orders/v2/#definition-processing_instruction for the list of payment_source that can be specified with this value."
        }
    ],
    "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
    "debug_id": "f34205434abxx",
    "links": [
        {
            "href": "https://developer.paypal.com/docs/api/orders/v2/#error-UNSUPPORTED_PROCESSING_INSTRUCTION",
            "rel": "information_link",
            "method": "GET"
        }
    ]
}

补充信息 #

• Hosted Fields字段渲染正常，输入功能无问题
• 该错误来自POST请求：https://cors.api.sandbox.paypal.com/v2/checkout/orders/7DY53846GN90xxxx/confirm-payment-source
• Postman测试相同接口返回同样错误
• 使用PayPal信用卡生成器生成的测试卡进行测试

问题原因与解决思路 #

核心原因 #

创建订单时设置了processing_instruction: "ORDER_COMPLETE_ON_PAYMENT_APPROVAL"，但这个指令仅支持PayPal钱包支付，信用卡支付（payment_source为card）不支持自动完成订单，因此触发了UNSUPPORTED_PROCESSING_INSTRUCTION错误。

解决步骤 #

1. 修改订单创建逻辑：检查后端创建订单的代码，移除processing_instruction参数的设置，或者不要设置为ORDER_COMPLETE_ON_PAYMENT_APPROVAL。
2. 手动捕获订单：当Hosted Fields提交成功（即hostedFieldsInstance.submit()返回成功）后，后端需要调用PayPal的v2/orders/{order_id}/capture接口，手动完成订单的捕获操作。
3. 修正代码拼写错误：前端代码中billigAddress是拼写错误，应该改为billingAddress，否则账单地址无法正确传递，可能引发额外的验证问题。

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