Document Properties
Kbid29291E
Last Modified04-Feb-2020
Added to KB22-Nov-2019
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
ProductICM 7.10

Concept - Order REST API (v1)

1 Introduction

This concept is valid for ICM version 7.10.13.4 and higher.

The intention of this document is to explain some special dynamic aspects of the order REST API that are not covered by the REST API documentation because of its nature describing the structure of requests and responses in a more static way. In most parts the Order REST API follows the same principles as the Basket REST API does.

1.1 Glossary

TermDescription
payment methodConfigured instance of a payment connector implementation to a specific provider. Also known as payment service.
payment instrumentA saved set of data to a payment service at a basket.
paymentPayment instrument set at the basket to pay with.

1.2 References

2 Order Resource

2.1 Versioning

A new version of the Order REST API had to be created since the new version (v1) is incompatible with the previous (legacy) Order REST interface for all requests. Hence, media-type-based versioning has been introduced to distinguish between legacy- and v1-related REST requests. A REST client must set the following HTTP Accept header in case of v1 requests:

HTTP Accept Header for V1 requests of Basket REST API
Accept: application/vnd.intershop.order.v1+json

In contrast, the standard media type header for JSON-based requests must be used to target requests of legacy Order REST API:

HTTP Accept Header for legacy requests of Basket REST API
Accept: application/json

This way requests of the legacy and v1 Order REST API can be used side by side by a REST client at the same time.

2.2 Order Creation

An order can be created by a POST request onto the orders resource. Starting with the new version of the REST API, it is now possible to support the different flows designed by the Order Creation Chain, which also interrupts the creation process (e.g. for performing a redirect to the payment service provider). The response contains a block providing details about the current state of the triggered creation process.

The first example shows how the response may look like when a payment redirect (for authorization) needs to be performed in order to complete the payment and the order.

Response: POST /orders?include=payments,payments.paymentInstrument,payments.paymentMethod
{
    "data": {
        "basket": "nNQKAB2_tMYAAAFuc9BdhmPm",
        "buckets": [
            "0"
        ],
        "commonShipToAddress": "TKwKAB2_oHgAAAFuQT1dhmTy",
        "commonShippingMethod": "STD_GROUND",
        "creationDate": "2019-11-13T14:27:06+01:00",
        "customer": "Patricia",
        "discounts": {},
        "documentNumber": "00000001",
        "id": "onUKAB2_eAQAAAFuFztdhmTy",
        "invoiceToAddress": "XcIKAB2_DWAAAAFuGD1dhmTy",
        "lineItems": [
            "PfwKAB2_vLQAAAFuSj1dhmTy"
        ],
        "orderCreation": {
            "status": "STOPPED",
            "stopAction": {
                "exitReason": "redirect_urls_required",
                "type": "Workflow"
            }
        },
        "payments": [
            "lgAKAB2_CTQAAAFuWj1dhmTy"
        ],
        "purchaseCurrency": "USD",
        "status": "Pending",
        "statusCode": "PENDING",
        "termsAndConditionsAccepted": true,
        "totalProductQuantity": 25,
        "totals": { ... // totals summary    },
        "user": "patricia@test.intershop.de"
    },
    "included": {
        "payments": {
            "lgAKAB2_CTQAAAFuWj1dhmTy": {
                "baseAmount": {
                    "currency": "USD",
                    "value": 628.34
                },
                "id": "lgAKAB2_CTQAAAFuWj1dhmTy",
                "openTender": true,
                "paymentCosts": { ... // payment costs summary  },
                "paymentInstrument": "ISH_ONLINEPAY",
                "paymentMethod": "ISH_ONLINEPAY",
                "redirectRequired": true,
                "status": "Unprocessed",
                "totalAmount": {
                    "currency": "USD",
                    "value": 628.34
                }
            }
        },
        "payments.paymentInstrument": {
            "ISH_ONLINEPAY": {
                "id": "ISH_ONLINEPAY"
            }
        },
        "payments.paymentMethod": {
            "ISH_ONLINEPAY": {
                "capabilities": [
                    "RedirectAfterCheckout"
                ],
                "description": "You will be redirected to the ISH Online Pay page after you submit your order.",
                "displayName": "ISH Demo Online Pay",
                "id": "ISH_ONLINEPAY",
                "paymentInstruments": [
                    "ISH_ONLINEPAY"
                ],
                "saveAllowed": true,
                "serviceID": "ISH_ONLINEPAY"
            }
        }
    },
    "infos": [
        {
            "code": "order.creation_stopped.info",
            "message": "The order process has not been finished yet."
        }
    ],
    "links": {
        "self": "http://<server>/INTERSHOP/rest/WFS/inSPIRED-inTRONICS-Site/-/orders/onUKAB2_eAQAAAFuFztdhmTy"
    }
}

The attribute states that the creation was STOPPED and why. In the current sample the URLs for the returning redirect need to be set. They can be set using a PATCH request on the order.

Request: PATCH /orders/<orderID>
{
	"orderCreation": {
		"status": "CONTINUE",
		"redirect": {
			"successUrl": "http://example.com/success",
			"cancelUrl": "http://example.com/cancel",
			"failureUrl": "http://example.com/failure"
		}
	}
}

The order creation is continued and may stop for another reason.

Response: PATCH /orders/<orderID>
{
    "data": {
        ...
        "orderCreation": {
            "redirect": {
                "cancelUrl": "http://example.com/cancel",
                "failureUrl": "http://example.com/failure",
                "successUrl": "http://example.com/success"
            },
            "status": "STOPPED",
            "stopAction": {
                "redirectUrl": "http://<server>/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/ISHPayRedirect-OnlinePay;pgid=k2mQ3pi7j0KRpDkmCMGi8gWz0000T82IF7s8;sid=DIAKAB2_GEQAAAFu.DxdhmT8?PaymentTransactionUUID=eGMKAB2_DqQAAAFuYz1dhmTy&transactionID=1573652282951&orderID=onUKAB2_eAQAAAFuFztdhmTy&paymentID=lgAKAB2_CTQAAAFuWj1dhmTy&merchant=0815&password=intershop&amount=62834¤cy=USD&site=inSPIRED-inTRONICS-Site&ita_fname=Patricia&ita_lname=Miller&ita_street=Potsdamer+Str.+20&ita_pcode=14483&ita_city=Berlin&ita_country=Germany&email=patricia%40test.intershop.de&successURL=http%3A%2F%2Fexample.com%2Fsuccess&failURL=http%3A%2F%2Fexample.com%2Ffailure&cancelURL=http%3A%2F%2Fexample.com%2Fcancel",
                "type": "Redirect"
            }
        },
        ...
    },
    ...
}

The process will continue until the order creation is completed successfully (or if it fails).

Even if the PATCH request to continue the order creation is sent after a (optional) notification by the PSP already completed the process, it is not harmed or restarted. All steps of the chain are checked and the final state returned.

2.3 Get Order List or Single Order

The request for returning all orders for the specified user behaves in the same way as the request for returning baskets. There is no separation between orders that are placed via the inSPIRED Storefront and the ones created by the REST API. Entries in the list are sorted in descending order according to the orders' creation date. This means that the user's current, i.e., most recently placed order is the first element in the list. If a valid orderID is given in the GET request, the details of the single order are returned together with the requested includes.

3 Order Payment Resource

Even though the number of calls are limited for payments at the order, the implementation uses the same technical approach as for the basket. In other words, it is also extensible as its counterpart at the basket. Below all possible API calls supported by the order payment resource and its speciality in the redirect handling are described.

3.1 Get Used Payments

Using the request, the client can resolve the list of (limited and open tender) payments used to pay the order. The request supports includes to retrieve also the related payment methods and payment instruments in a single request.

Response: GET /orders/<orderID>/payments?include=paymentInstrument,paymentMethod
{
    "data": [
        {
            "baseAmount": {
                "gross": {
                    "currency": "USD",
                    "value": 13055.07
                }
            },
            "id": "open-tender",
            "paymentCosts": {
                "gross": {
                    "currency": "USD",
                    "value": 0
                },
                "net": {
                    "currency": "USD",
                    "value": 0
                },
                "tax": {
                    "currency": "USD",
                    "value": 0
                }
            },
            "paymentInstrument": "ISH_CASH_ON_DELIVERY",
            "paymentMethod": "ISH_CASH_ON_DELIVERY",
            "totalAmount": {
                "gross": {
                    "currency": "USD",
                    "value": 13055.07
                }
            }
        }
    ],
    "included": {
        "paymentMethod": {
            "ISH_CASH_ON_DELIVERY": {
                "default": false,
                "description": "Just pay your order directly when it gets delivered!",
                "displayName": "Cash on Delivery",
                "id": "ISH_CASH_ON_DELIVERY",
                "paymentInstruments": [
                    "ISH_CASH_ON_DELIVERY"
                ],
                "restricted": false,
                "saveAllowed": true
            }
        },
        "paymentInstrument": {
            "ISH_CASH_ON_DELIVERY": {
                "id": "ISH_CASH_ON_DELIVERY"
            }
        }
    }
}

3.2 Prepare and Handle Redirect After Checkout

3.2.1 General Workflow

workflow redirect after checkout no notification

workflow redirect after checkout with notification

3.2.2 Prepare Redirect While Creating Payment

This request is only supported by the basket if the payment method supports a kind of redirecting workflow. The request can be used for all kinds of redirect.

See Request for Basket Payments Resource for details.

3.2.3 Prepare Redirect Using Separate Request

In case the redirect URLs are not set while assigning the payment, the order creation cannot be completed and stops. The URLs have to be set later. The data can be provided within the orderCreation object in the section redirect. Afterwards the URL for redirecting the customer to the PSP can be generated and is reported back.

Request: PATCH /orders/<orderID>
{
	"orderCreation": {
		"status": "CONTINUE",
		"redirect": {
			"successUrl": "http://example.com/success",
			"cancelUrl": "http://example.com/cancel",
			"failureUrl": "http://example.com/failure"
		}
	}
}
Response: PATCH /orders/<orderID>
{
    "data": {
        "basket": "oC8KAB2_2N0AAAFrG9kBr5h5",
        "buckets": [
            "0"
        ],
        "commonShipToAddress": "jUIKAB2_X.wAAAFrcP44a5lI",
        "commonShippingMethod": "STD_GROUND",
        "customer": "Patricia",
        "discounts": {},
        "documentNumber": "00000353",
        "id": "3ycKAB2_A8wAAAFrW_44a5lI",
        "invoiceToAddress": "OskKAB2_JVkAAAFrYP44a5lI",
        "lineItems": [
            "4QAKAB2_zOwAAAFrcf44a5lI"
        ],
        "orderCreation": {
            "redirect": {
                "cancelUrl": "http://example.com/cancel",
                "failureUrl": "http://example.com/failure",
                "redirectUrl": "http://icm-server/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/ISHPayRedirect-OnlinePay;pgid=t4uQ3pi73K6RpDktBA.rXsCb00001UeHgPZz;sid=y2IKAB2_X8cAAAFrag04a5lJ?PaymentTransactionUUID=6hgKAB2_dHIAAAFrd_44a5lI&transactionID=1561644830294&merchant=0815&password=intershop&amount=62834¤cy=USD&ita_fname=Patricia&ita_lname=Miller&ita_street=Potsdamer+Str.+20&ita_pcode=14483&ita_city=Berlin&ita_country=Germany&email=patricia%40test.intershop.de&successURL=http%3A%2F%2Fexample.com%2Fsuccess&failURL=http%3A%2F%2Fexample.com%2Ffailure&cancelURL=http%3A%2F%2Fexample.com%2Fcancel",
                "successUrl": "http://example.com/success"
            },
            "status": "STOPPED",
            "stopAction": {
                "redirectUrl": "http://jrwilms01:10080/INTERSHOP/web/WFS/inSPIRED-inTRONICS-Site/en_US/-/USD/ISHPayRedirect-OnlinePay;pgid=t4uQ3pi73K6RpDktBA.rXsCb00001UeHgPZz;sid=y2IKAB2_X8cAAAFrag04a5lJ?PaymentTransactionUUID=6hgKAB2_dHIAAAFrd_44a5lI&transactionID=1561644830294&merchant=0815&password=intershop&amount=62834¤cy=USD&ita_fname=Patricia&ita_lname=Miller&ita_street=Potsdamer+Str.+20&ita_pcode=14483&ita_city=Berlin&ita_country=Germany&email=patricia%40test.intershop.de&successURL=http%3A%2F%2Fexample.com%2Fsuccess&failURL=http%3A%2F%2Fexample.com%2Ffailure&cancelURL=http%3A%2F%2Fexample.com%2Fcancel",
                "type": "Redirect"
            }
        },
        "payments": [
            "open-tender"
        ],
        "status": "Pending",
        "statusCode": "PENDING",
        "termsAndConditionsAccepted": true,
        "totalProductQuantity": 25,
        "totals": { ... },
        "user": "patricia@test.intershop.de"
    },
    "infos": [
        {
            "code": "order.creation_stopped.info",
            "message": "The order process is not yet finished."
        }
    ],
    "links": {
        "self": "http://jrwilms01:10080/INTERSHOP/rest/WFS/inSPIRED-inTRONICS-Site/-/orders/3ycKAB2_A8wAAAFrW_44a5lI"
    }
}

3.2.4 Handle Callback from Redirect

As soon as the customer is redirected back from the PSP to the shop (REST client), the client has to collect all data and pass the parameters to the ICM server using a PATCH request for the current order.

Request: PATCH /orders/<orderID>
{
	"orderCreation": {
		"status": "CONTINUE",
		"redirect": {
			"status": "SUCCESS",
			"parameters" : [
	           {
				    "name": "transactionID", 
					"value": "id from provider" 
	           }
	        ]
		}
	}
}
Response: PATCH /orders/<orderID>
{
    "data": {
        "basket": "oC8KAB2_2N0AAAFrG9kBr5h5",
        "buckets": [
            "0"
        ],
        "commonShipToAddress": "jUIKAB2_X.wAAAFrcP44a5lI",
        "commonShippingMethod": "STD_GROUND",
        "customer": "Patricia",
        "discounts": {},
        "documentNumber": "00000353",
        "id": "3ycKAB2_A8wAAAFrW_44a5lI",
        "invoiceToAddress": "OskKAB2_JVkAAAFrYP44a5lI",
        "lineItems": [
            "4QAKAB2_zOwAAAFrcf44a5lI"
        ],
        "orderCreation": {
            "status": "COMPLETED"
        },
        "payments": [
            "open-tender"
        ],
        "status": "Pending",
        "statusCode": "PENDING",
        "termsAndConditionsAccepted": true,
        "totalProductQuantity": 25,
        "totals": { ... },
        "user": "patricia@test.intershop.de"
    },
    "links": {
        "self": "http://jrwilms01:10080/INTERSHOP/rest/WFS/inSPIRED-inTRONICS-Site/-/orders/3ycKAB2_A8wAAAFrW_44a5lI"
    }
}

When the status is updated, the request handler has to create a new order creation context and trigger the order creation again. Now the workflow can continue. In case the payment works in an asynchronous manner, the outcome may still be a pending order. The status of the order creation chain is STOPPED with the reason waiting_for_pending_payments. When the notification from the PSP arrives, the order creation continues. Depending on the payment status, the order may be rolled back (order creation status ROLLED_BACK with additional info code order.cancelled.info) or is completed (order status NEW).

3.2.5 Order Creation States

Order Creation StatusStop ActionInfo CodeOrder StatusPayment StatusNote
COMPLETED

NEWAUTHORIZED
CAPTURED
Final state. Order was created.
ROLLED_BACK
order.cancelled.infoPAYMENT_CANCELLEDAUTHORIZATIONVOIDEDThe payment failed or the user canceled the payment on the PSP pages. The order was rolled back and the basket restored. The user has to submit the order again.
STOPPEDExitReason = redirect_urls_requiredorder.creation_stopped.infoPENDINGPENDINGSet URLs for redirecting back from the PSP to the shop.
STOPPEDRedirectUrl available
PENDINGPENDINGRedirect user to provided URL. When returning, write data from response.
STOPPEDExitReason = waiting_for_pending_paymentsorder.creation_stopped.infoPENDINGAUTHORIZED (pending)
CAPTURED (pending)
Order was successfully created but is waiting for a notification from the PSP. The client can show a message, stating that the order was placed and the payment is in progress. A following GET to the order item will inform about the state.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets