PayPal Adaptive Payments: transactionStatus vs senderTransactionStatus

Question

I am using PayPal adaptive payments. I am retrieving PaymentDetails details here https://developer.paypal.com/docs/classic/api/adaptive-payments/PaymentDetails_API_Operation/

What isn't clear to me is the difference between senderTransactionStatus and transactionStatus?

What's even more strange is I can have the following scenario:

status: COMPLETED
paymentInfoList.paymentInfo.transactionStatus: null
paymentInfoList.paymentInfo.senderTransactionStatus: PENDING
paymentInfoList.paymentInfo.pendingReason: SOME REASON

How can it be that status is COMPLETE, but senderTransactionStatus is PENDING, and transactionStatus if null?

I have no idea which status I should use, or even how to use them in combination to report correct status back to my users.

Ive read the documentation, but still none the wiser.

Answer 1

status has to do with the payment being submitted. This will show completed as long as the payment has moved into processing (ie; funds are moving or pending move and the transaction was not declined).

senderTransactionStatus has to do with the funds leaving the senders account. It would show completed if it is an INSTANT payment (that completed): creditcard, instant transfer, balance transfer. Pending would show if the funds are on hold because of eCheck, Sending Limits, Risk Review, etc. There are a list of pendingReasons on the PaymentDetails API page. OTHER may mean something that is not disclosed to either party due to privacy policy: it could be compliance related, Remittance Transfer Rule, etc.

transactionStatus should be completed once the receiver has the funds in their account. Though, this can change depending on what is happening with the transaction. IE: refunds, holds because of chargebacks, reversals due to risk or unauthorized account access. Edit: This will be NULL if the email address of the receiver is NOT VALID. pendingReason will say UNILATERAL because this email address does not exist in the system and is UNCLAIMED

If the transactionStatus is not NULL, it and senderTransactionStatus will always be the same. This includes being pending for Payment Review, Manually accepting currency, eCheck, Instant Bank Transfer. Everything.