Discuss and specify create order API

[andrii-kovalenko-ct]

As discussed with @butenkor now the API is not described well.

https://github.com/commercetools/commercetools-payment-to-order-processor/blob/master/doc/REQUIREMENTS.MD

The basic point is: we should describe all possible cases and specify expected result in the cases, like:

• what HTTP response status are expected in different cases
• what HTTP response body expected
• mime type
• should a email notification be sent about a new order creation or this should be a responsibility of another process (see https://github.com/commercetools/commercetools-order-message-processor)
• what are the cases?
  • order successfully created
  • order already exists
  • payment is not valid (and different cases: no transaction, transaction cancelled, wrong amount etc)
  • order number not found
  • order can't be created with a reason
  • decryption problem
  • cart can't be found
  • etc

Like an initial proposition: in case we received a request we should always return 200 (OK) response and JSON body with the result - successful or failed.

[andrii-kovalenko-ct]

As discussed with @butenkor and @ahalberkamp the api should return the next HTTP statuses:

• 201 if the order successfully created
• 200 if the request is correct, but an order can't be created for this cart (for instance, order already exists, or payment is cancelled)
• any other - the request can't be processed right now for any reason (the service is out of order, encryption problem, unexpected exception, connection lost and so on)

The response mime type is application/json.

The response body is optional JSON and may contain a reason why order is not created.

[ahalberkamp]

sound good for me! I

[butenkor]

@andrii-kovalenko-ct +1 o last comment. Small correction: or payment is cancelled - If payment is cancelled than there should be no transaction with state = Success, right? Another valid example would be if ```or total amount of the cart does not match paid amount anymore (for example due to expired applied discount)

[andrii-kovalenko-ct]

if payment is cancelled, than it has last transaction CANCEL with status aSUCCESS`. Isn't it? Or you mean that i should change transaction cancelled -> payment cancelled?

[andrii-kovalenko-ct]

So, the latest update is:

1. API call: on successful order creation shop should return http status code 201

2. API call: status code 200 should be returned if there was an error from which shop can not recover from (expired cart discount, payment amount is less than current cart amount) and order create retry would lead to same error anyway. In this case shop should also log an error so that this case can be easily identified by logs alerting and customer notified (error message should contain all necessary data like: reason, cart id, payment id, payment referenceId (intended orderNumber taken from payment object), payone payment txid)

   3. API call: 400 should be returned if payment to order should retry URL as for example shop run into unexpected state like wrong CTP credentials or wrong encryption key and cart id can not be decrypted ( btw.: payment to order will also retry on any status code unequal 200 or 201 so 5xx errors are covered also but it should only be the case of web app server crash)

   4. API request should create order only if cart state is NOT ordered. In case it is ordered it should reply with status code 200 (as mentioned above)

   5. API implementation payment/cart validation, order creation and email sending should be implemented that way that it can be reused in normal order creation.

   6. in API implementation order can be only created if cart has at least one (might first one) payment which fulfils following criteria:

      • has transaction of type AUTHORISE or CHARGE and status "Success"
      • successful transaction amount >= cart totalAmount
      • does not have transaction of type cancel/refund and "successful transaction amount" minus "refund amount" is not smaller than "cart totalAmount" (This case should be logged as it would need manual processing also i.e.: partial refund or order cancel)

[andrii-kovalenko-ct]

released

https://github.com/commercetools/commercetools-payment-to-order-processor/pull/22

https://github.com/commercetools/commercetools-payment-to-order-processor/releases/tag/v0.4