PayPal SDK REST API状态辨析及支付完全完成确认方法

Hey there, let's untangle these PayPal status fields because I remember being confused by them too when I first worked with the REST API! Here's a clear breakdown:

1. Differences Between approved, completed, and verified #

Each status lives in a different part of the API response and represents a distinct step in the payment flow:

• approved (root state field)
  This means the payer has authorized the payment—they've clicked "Pay Now" and confirmed their intent to pay. At this stage, the payment is authorized but might not have been executed (e.g., for delayed captures or pre-authorized payments). The money hasn't yet moved to your account.

• completed (sale object state field)
  Found inside transactions[].related_resources[].sale, this is the critical status for confirming a successful, finalized payment. It means the funds have been successfully transferred from the payer's account (or their funding source) to your PayPal balance (or are in transit for settlement). This is the "payment done" marker you care about for order fulfillment.

• verified (payer.status field)
  This refers to the payer's PayPal account being verified by PayPal (they've confirmed their identity, linked a bank/card, etc.). It's a trust indicator for the payer's legitimacy, but it has nothing to do with the payment's completion status—an unverified payer can still complete a payment, and a verified payer's payment could fail or be pending.

2. How to Confirm a Fully Completed ("completed-completed") Payment #

To be 100% sure a payment is fully finalized and ready to trigger your checkout flow (like shipping goods or granting access), you need to check two key fields together:

1. The root-level state must be approved (confirms the payer authorized the payment).
2. At least one sale object under transactions[].related_resources must have a state of completed (confirms the funds have been transferred).

The payer.status being VERIFIED is optional but can add an extra layer of confidence in the transaction's legitimacy—though it's not required to proceed with fulfillment.

Here's a simplified snippet of what a fully completed payment response looks like:

{
  "state": "approved",
  "payer": {
    "status": "VERIFIED",
    "payer_info": { /* ... */ }
  },
  "transactions": [
    {
      "related_resources": [
        {
          "sale": {
            "id": "7S848712MN1654304",
            "state": "completed",
            "amount": { /* ... */ },
            "create_time": "2024-05-20T12:34:56Z"
          }
        }
      ]
    }
  ]
}

Pro tip: Always fetch the latest payment status via the API (using the payment ID) instead of relying solely on initial webhook responses, just to account for any edge cases like delayed settlement or status updates.

内容的提问来源于stack exchange，提问作者Mohd Abdul Mujib