PayPal IPN parameters contain two status fields. Which should I use? - paypal-ipn

I'm using the PayPal Adaptive Payments API. I have a script that receives the IPN postback when a payment is made. In this script I need to perform validation, including checking that the status of the payment is COMPLETED, as specified by the documentation:
Confirm that the "payment_status" is "Completed," since IPNs are also sent for other results such as "Pending" or "Failed"
The documentation hasn't been updated for Adaptive Payments which use different parameters (not payment_status). The parameters I receive are documented here and there are two status fields:
status
The status of the payment. Possible values are:
CREATED – The payment request was received; funds will be transferred once the payment is approved
COMPLETED – The payment was successful
INCOMPLETE – Some transfers succeeded and some failed for a parallel payment or, for a delayed chained payment, secondary receivers have not been paid
ERROR – The payment failed and all attempted transfers failed or all completed transfers were successfully reversed
REVERSALERROR – One or more transfers failed when attempting to reverse a payment
PROCESSING – The payment is in progress
PENDING – The payment is awaiting processing
and
transaction[n].status
The transaction status, where [n] is a number from 0 to 5. For simple single-receiver payments, this number will be 0. Numbers larger than 0 indicate the payment to a particular receiver in chained and parallel payments.
Possible values are:
Completed
Pending
Refunded
Simply put, I don't know which one I should be using. The payment status or the transaction status?
(I'd place my bets on transaction status but then I don't know what the purpose of the payment status is when you have more than one transaction in a request (when using chained payments, for example). Then again, the payment status has more possible values, so perhaps that's the "overall" status and should be used.)

You would want to look at transaction[n].status, and this would be an array. This is because with adaptive payments, a single transaction can be split into multiple transactions to different merchants.
The status is just saying that the api call went through and completed successfully. It was processed. The transaction[n].status tells you what the status is of each transaction in that call.

Related

Get status of Paypal NVP correlationid

I have a transaction with "Correlationid" with Paypal's Express Checkout NVP API. How can I get the details for this correlationid as to whether the transaction was completed or denied?
The CorrelationID is pretty much useless as the transactionID is used in reference lookup such as this. The best solution here to do is run the GETTRANSACTIONDETAILS API call for Express Checkout using the:
PAYMENTSTATUS Status of the payment.
It is one of the following values:
None — No status
Canceled-Reversal — A reversal has been canceled, for example, when you win a dispute and the funds for the reversal have been returned to you.
Completed — The payment has been completed, and the funds have been added successfully to your account balance.
Denied — You denied the payment. This happens only if the payment was previously pending because of possible reasons described for the PendingReason element.
Expired — The authorization period for this payment has been reached.
Failed — The payment has failed. This happens only if the payment was made from your buyer's bank account.
In-Progress — The transaction has not terminated, for example, an authorization may be awaiting completion.
Partially-Refunded — The payment has been partially refunded.
Pending — The payment is pending. See the PendingReason field for more information.
Refunded — You refunded the payment.
Reversed — A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer. The reason for the reversal is specified in the ReasonCode element.
Processed — A payment has been accepted.
Voided — An authorization for this transaction has been voided.
Here is a document to assist you with this call and parameters:
GetTransactionsDetails API

Handling Paypal payment status 'Completed-Funds-Held' with time-sensitive goods

Good morning, I'm working with DoExpressCheckout's Payment Status response for an InstantPaymentOnly Sale.
https://developer.paypal.com/docs/classic/api/merchant/DoExpressCheckoutPayment_API_Operation_NVP/
By PAYMENTINFO_n_PAYMENTSTATUS all possible responses are shown, Completed-Funds-Held is the latest addition.
I'm providing a service that expires and must be used by a certain time. If the payments final status is not known by the time the service must start, its looks like we're going to have to collect payment (again) in person and refund the online payment. Needless to say, that doesn't sound good.
Q. Could Completed-Funds-Held result in funds never being deposited to the main balance?
The documentation for that particular status lists two possible response codes that go along with Completed-Funds-Held: newsellerpaymenthold (not applicable in my case) and paymenthold which vaguely states "A hold is placed on the merchant's transaction for a reason not listed."
Basically is Completed-Funds-Held a "successful" transaction where the purchaser can receive his product without risk of the seller never receiving payment?
EDIT: Is Completed-Funds-Held a final status if the payment is successful? Or will a Completed IPN request come if and when the hold is settled?
Those payments will eventually become available. What you should do is setup an IPN solution so that you can automatically update your system when a payment hold is released. The same would be true for things like e-checks where the payment status is simply pending and then clears a few days later.

PayPal Adaptive Payments: transactionStatus vs senderTransactionStatus

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.
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.

PayPal adaptive payment delayed chained payment's receiver configurations

I am using PayPal adaptive payment delayed chained payment. The process is unintuitive.
Q1: How to process the payment to the secondary receiver?
API calls are made as below:
1. Make Pay API call with actionType=PAY_PRIMARY which will only process the payment to the primary receiver
2. Explicitly process the payment to secondary receiver.
How do I process step 2 above? Do I use ExecutePayment API operation? (This does not look correct since in the documentation it says to use payKey however payKey would be expired by the time I need to process the payment to the secondary receiver.)
Q2: Is it ok to use SECONDARYONLY as feesPayer in delayed chained payment?
A1: You would make a call to ExecutePayment passing the PayKey as a parameter. To clear up your doubts, the PayKey has a shelf life of 3 hours before the payment is initiated.
Once the payment has been approved by the customer (i.e. the first leg of the chained payment is completed) the PayKey becomes permanent and does not expire.
For a delayed chained payment, PayPal gives you 90 days to explicitly complete the second leg. After that, it will not allow you to do so, and the primary would need to manually send the money to the secondary receiver.
A2: Yes, but you can only use this variable when you have a single secondary receiver.

PayPal Subscription Payment Failed

When a subscription payment fails, PayPal will retry for n times.
What transaction type (subscr_cancel or subscr_eot) is sent back via IPN, after all retries fail?
The specifics depend on the PayPal product you're using, although the logic works similar(`ish) across both Website Payments Standard subscription buttons and Express Checkout Recurring Payments (via the CreateRecurringPaymentsProfile API):
This depends on whether you've set MAXFAILEDPAYMENTS or not. If MAXFAILEDPAYMENTS > 0 is set, it will cancel the subscription after n number of attempts and you'll receive a subscr_cancel. If you have it set to MAXFAILEDPAYMENTS=0, you'll get recurring_payment_skipped and the recurring payment will be marked as having an outstanding balance. If you specify AUTOBILLOUTAMT=AutoBillAmt, the outstanding balance will be added to the next billing cycle.
I would suggest taking a look at https://cms.paypal.com/us/cgi-bin/?cmd=_render-content&content_ID=developer/e_howto_html_IPNandPDTVariables#id091EB0901HT which lists all IPN variables, including the ones for recurring payments.
Paypal returns subscr_failed for this case, and the possible return values are:
subscr_signup: subscription sign-up.
subscr_cancel: subscription cancellation.
subscr_failed: subscription payment failure.
subscr_payment: subscription payment.
subscr_eot: subscription’s end-of-term.
subscr_modify: subscription modification.
Please click here for further clarification.