Orders v2 Capture Status Possible Values

[shawnz]

Hi there, we are trying to integrate the orders v2 API into a new application, which is replacing a previous application that used the NVP API.

I had some questions about the order capture process in the new API.

In the docs (https://developer.paypal.com/docs/api/orders/v2/#orders_capture) we see that the possible statuses upon a successful order capture are as follows:

• CREATED.
• SAVED.
• APPROVED.
• VOIDED.
• COMPLETED.

Besides "COMPLETED", It's not clear to me in what situations these statuses might occur. For example, since we are making the orders with INTENT = CAPTURE, is it ever possible to see the statuses such as "CREATED", "SAVED", "APPROVED", etc? Do we need to check this before releasing the product to the user, or is receiving a 200/201 status enough?

Furthermore, in the result returned we have the field purchase_units[].payments[].captures[].status. Is this something we need to check after a capture and what are the possible values here? Is it possible for more than one capture or payment to be returned in the array and if so, how do we know which one to check for the status?

Thanks, Shawn

[shawnz]

Hi again, It seems like my thread has been moved to the "NVP/SOAP APIs" forum but my question is about the REST APIs. Could it be moved back?

[shawnz]

Bump

Sorry to be a bother again @not_here , but is there any way you could give me some input on this issue?

[not_here · Accepted solution]

HI @shawnz,

Since you are using the intent=capture in your Create Order requests, you will only see the Create status (when you initially create the order) and Completed for when you actually capture the order.

With regards to your question "in the result returned we have the field purchase_units[].payments[].captures[].status. Is this something we need to check after a capture and what are the possible values here?", this only applies if you are doing multi-capture on an authorization. 

Let me know if this helps!

Thanks,

Christina 

Was my post helpful? If so, please give me a kudos!

[shawnz]

THANK YOU Christina! That is indeed a big help. FWIW I think a quick note to that effect would be a valuable addition to the docs.

I also had one more related question which you could hopefully help me with. I have noticed in the source code for the smart payment buttons, that they will automatically restart checkout in the case of an INSTRUMENT_DECLINED or PAYER_ACTION_REQUIRED error on capture. In the case of any other error on capture, they will do nothing.

However since I am doing the capture server-side rather than with the actions.order.capture() function on the client, I will be processing the capture response myself. Should I copy the behaviour indicated above, i.e. call actions.restart() in the case of an INSTRUMENT_DECLINED or PAYER_ACTION_REQUIRED error, and do nothing otherwise?

I have also noticed this page: https://developer.paypal.com/docs/checkout/integration-features/funding-failure/ where they indicate that the correct response to an INSTRUMENT_DECLINED is to call actions.restart(). However they don't address PAYER_ACTION_REQUIRED, while the built-in code does. Does that mean I should not try to handle PAYER_ACTION_REQUIRED myself if I'm doing a server-side capture?

Finally, in the case of an error which is not one of those two, would it be acceptable to try restarting the checkout anyway? Or should I simply display an error to the client and tell them that they will not be able to purchase the product? Is there ever a case where money will be taken from the customer even though the capture did not return a 200/201 success? Or can we be sure that money is taken if and only if the capture returns a 200/201 status?

Thank you for your time!!!

Shawn

[not_here]

Hi @shawnz, 

I'm working on getting the answers to your questions. I agree that these details should be put into our documentation. Once I have all the right answers I will work with our team to get this information included. 

Thanks,
Christina 

[shawnz]

Thank you!!

[not_here]

Hi @shawnz,

Here's what I've got so far. I'm still working internally with teams to get some answers, so bare with me while I work to get those.

• The second question answers the first one.
• The second question is pending.
• The third question (assuming both errors should be handled with restart()), any other errors won't be solved by sending the customer back through the PP flow and need to be handled based on what the error is.

I'll post when I have an answer to question #2

Thanks,
Christina 

Was my post helpful? If so, please give me a kudos!

[shawnz]

Thank you so much Christina. This is all very helpful information for our project.

If it helps you at all, it seems like the PAYER_ACTION_REQUIRED behaviour was added by a user named @bluepnume . See: https://github.com/paypal/paypal-smart-payment-buttons/commit/b76b098d5bee873d6c386b2026850efa00a67e...

Shawn

[shawnz]

Some more details to this mystery...

For testing purposes, I tried completing a transaction in the live environment with known bad information (sorry!) and I observed that neither INSTRUMENT_DECLINED nor PAYER_ACTION_REQUIRED resulted. Instead, the declined message was shown right to the user in the Paypal checkout dialog, without the order ever being approved or control being returned to my code. Example: https://imgur.com/a/IdjXBVu

Does this mean that we actually dont have to handle INSTRUMENT_DECLINED at all?