传递税费金额时PayPal v2 Checkout Orders返回422状态码

问题场景 #

使用Standard PayPal Checkout实现支付功能，期望展示如下金额结构：

Sub-total  $249
Tax        $24.9
Total      $273.9

但添加tax字段后，调用/v2/checkout/orders接口返回422状态码，错误信息如下：

Error: /v2/checkout/orders returned status 422 (Corr ID: 86fc10bc7f8cc).
{"name":"UNPROCESSABLE_ENTITY","details":[{"field":"/purchase_units/@reference_id=='default'/amount/breakdown/item_total/value","value":"273.9","issue":"ITEM_TOTAL_MISMATCH","description":"Should equal sum of (unit_amount * quantity) across all items for a given purchase_unit"}],"message":"The requested action could not be performed, semantically incorrect, or failed business validation.","debug_id":"86fc10bc7f8cc","links":[{"href":"https://developer.paypal.com/docs/api/orders/v2/#error-ITEM_TOTAL_MISMATCH","rel":"information_link","method":"GET"}]}

错误原因 #

1. 金额结构嵌套错误：你在breakdown.item_total内嵌套了tax字段，PayPal API规范中item_total仅代表商品小计（不含税），税费需要作为breakdown的独立顶级字段（tax_total）存在。
2. 地址字段名错误：shipping地址中的字段名不符合PayPal API要求（如addline_1应为address_line_1，poscode应为postal_code等），这也可能导致接口校验失败。

修正后的代码 #

<div id="paypal-button-container"></div>

<script>
  paypal.Buttons({
    createOrder: function(data, actions) {
      return actions.order.create({
        "purchase_units": [{
          "amount": {
            "currency_code": "AUD",
            "value": "273.9",
            "breakdown": {
              "item_total": {  /* 仅代表商品小计，不含税 */
                "currency_code": "AUD",
                "value": "249"
              },
              "tax_total": {  /* 汇总所有商品的税费 */
                "currency_code": "AUD",
                "value": "24.9"
              }
            }
          },
          "shipping": {
            "name": {
              "full_name": "TestBuyer"
            },
            "address": {
              "address_line_1": "1234 Main St",
              "admin_area_2": "New San Jose",
              "admin_area_1": "CA",
              "postal_code": "9513",
              "country_code": "AT"
            }
          },
          "items": [
            {
              "name": "First Product Name", 
              "description": "Optional descriptive text..",
              "unit_amount": {
                "currency_code": "AUD",
                "value": "249"
              },
              "tax": {
                "value": "24.9",
                "currency_code": "AUD"
              },
              "quantity": "1"
            }
          ]
        }]
      });
    },
    onApprove: (data, actions) => {
      return actions.order.capture().then(function(orderData) {
        console.log('Capture result', orderData, JSON.stringify(orderData, null, 2));
        const transaction = orderData.purchase_units[0].payments.captures[0];
        alert(`Transaction ${transaction.status}: ${transaction.id}\n\nSee console for all available details`);
      });
    }
  }).render('#paypal-button-container');
</script>

关键修正说明 #

• 将原item_total内的tax字段移除，在breakdown下新增tax_total字段，用于汇总所有商品的税费金额
• 修正shipping地址的字段名，确保完全符合PayPal API的字段命名规范
• 确保金额校验逻辑匹配：amount.value = item_total.value + tax_total.value（249 + 24.9 = 273.9），同时tax_total.value等于所有items中tax.value的总和

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