The PaymentDetails API Operation

The PaymentDetails API is used to obtain information about a payment. You can identify the payment by your tracking ID, the PayPal transaction ID in an IPN message, or the pay key associated with the payment. Table 4-2 summarizes the common request parameters.

In short, you pass in one of several possible values that identifies a payment to PaymentDetails, and it returns relevant status information about the payment. Example 4-2 illustrates a trivial Bash script that makes a PaymentDetails API request using a payKey value returned from Example 4-1. Example usage for the script is to simply pass in the pay key as a command-line parameter to the script.

#!/bin/bash

PAYKEY="${1}"

USERID="XXX"
PASSWORD="XXX"
SIGNATURE="XXX"

APPID="APP-80W284485P519543T"

RESULT=$(curl -s --insecure -H "X-PAYPAL-SECURITY-USERID: $USERID" -H "X-PAYPAL-SECURITY-PASSWORD: $PASSWORD" -H "X-PAYPAL-SECURITY-SIGNATURE: $SIGNATURE" -H "X-PAYPAL-REQUEST-DATA-FORMAT: NV" -H "X-PAYPAL-RESPONSE-DATA-FORMAT: JSON" -H "X-PAYPAL-APPLICATION-ID: $APPID" https://svcs.sandbox.paypal.com/AdaptivePayments/PaymentDetails -d "requestEnvelope.errorLanguage=en_US&payKey=$PAYKEY";)

echo $RESULT

Sample results from the script follow and illustrate the basic format of a PaymentDetails response:

{ "actionType" : "PAY",
  "cancelUrl" : "http://example.com/cancel",
  "currencyCode" : "USD",
  "feesPayer" : "EACHRECEIVER",
  "ipnNotificationUrl" : "http://example.com/ipn",
  "memo" : "Simple payment example.",
  "payKey" : "AP-4U527241GF1114245",
  "paymentInfoList" : { "paymentInfo" : [ { "pendingRefund" : "false",
            "receiver" : { "amount" : "1.00",
                "email" : "XXX",
                "paymentType" : "SERVICE",
                "primary" : "false"
              }
          } ] },
  "responseEnvelope" : { "ack" : "Success",
      "build" : "2428464",
      "correlationId" : "4808cadb5297e",
      "timestamp" : "2012-01-14T17:58:11.358-08:00"
    },
  "returnUrl" : "http://example.com/return",
  "reverseAllParallelPaymentsOnError" : "false",
  "sender" : { "useCredentials" : "false" },
  "status" : "CREATED"
}

Of particular interest in the response for PaymentDetails is the status field that indicates that the payment request has been created but not yet completed; however, should you visit https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_ap-payment&paykey=AP-4U527241GF1114245 and successfully approve the payment, invoking PaymentDetails again should return a status of COMPLETED. However, a status of COMPLETED does not necessarily mean that the payment was successfully processed and that payment was rendered—it only means that the request, regardless of its ultimate outcome—was completed successfully. If the status were COMPLETED, additional information would be included regarding the specific details as they relate to the payment(s). For example, the following sample results show a PaymentDetails response where status is COMPLETED and the paymentInfoList field provides definitive information about the ultimate outcome of the payment. (In the case of an eCheck payment, the transactionStatus would have been PENDING.)

{
  "status": "COMPLETED", 
  "responseEnvelope": {
    "ack": "Success", 
    "timestamp": "2012-01-31T22:47:32.121-08:00", 
    "build": "2486531", 
    "correlationId": "e28c831c96f87"
  }, 
  "returnUrl": "http://example.com", 
  "payKey": "AP-72S344750E3616459", 
  "senderEmail": "XXX", 
  "actionType": "PAY", 
  "sender": {
    "email": "matthe_1325995267_per@zaffra.com", 
    "useCredentials": "false"
  }, 
  "paymentInfoList": {
    "paymentInfo": [
      {
        "refundedAmount": "0.00", 
        "receiver": {
          "paymentType": "SERVICE", 
          "amount": "9.99", 
          "email": "XXX", 
          "primary": "false"
        }, 
        "transactionId": "2NB983427X665902U", 
        "senderTransactionStatus": "COMPLETED", 
        "senderTransactionId": "11411689C90721011", 
        "pendingRefund": "false", 
        "transactionStatus": "COMPLETED"
      }
    ]
  }, 
  "currencyCode": "USD", 
  "cancelUrl": "http://example.com/cancel", 
  "feesPayer": "EACHRECEIVER", 
  "reverseAllParallelPaymentsOnError": "false"
}

If you’re comfortable working in a Linux or Unix environment or can comfortably execute curl commands in a Windows environment, it’s worthwhile to try manually executing these scripts to ensure that you understand the fundamentals. Regardless, in the next section, we’ll implement the same logic as a GAE project.