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.
Glossary
| Term | Description |
|---|---|
| payment method | Configured instance of a payment connector implementation to a specific provider. Also known as payment service. |
| payment instrument | A saved set of data to a payment service at a basket. |
| payment | Payment instrument set at the basket to pay with. |
References
- Business Guide - WebShop REST API - Basket and Checkout (v0)
- Concept - Basket REST API (v1) (Valid to 7.10)
- Concept - Order Creation
Order Resource
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:
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:
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.
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.
Info
The segment buyer (see code below) is included from ICM version 7.10.38 and higher.
{
"data": {
"basket": "nNQKAB2_tMYAAAFuc9BdhmPm",
"buckets": [
"0"
],
"buyer": {
"accountID": "patricia@test.intershop.de",
"customerNo": "Patricia",
"email": "patricia@test.intershop.de",
"firstName": "Patricia",
"lastName": "Miller",
"secondName": "Magdalena",
"title": "Ms.",
"userNo": "patricia"
},
"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.
{
"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.
{
"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.
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.
Order Payment Resource
Even though the number of calls for payments are limited at the order, the implementation uses the same technical approach as for the basket. In other words, it is also extensible like its counterpart at the basket. Below you can find a description of all possible API calls supported by the order payment resource and its speciality in the redirect handling.
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.
{
"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"
}
}
}
}
Prepare and Handle Redirect After Checkout
General Workflow
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 Requests for Basket Payments Resource for details.
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.
{
"orderCreation": {
"status": "CONTINUE",
"redirect": {
"successUrl": "http://example.com/success",
"cancelUrl": "http://example.com/cancel",
"failureUrl": "http://example.com/failure"
}
}
}
Info
The segment "buyer" is included from ICM version 7.10.38 and higher.
{
"data": {
"basket": "oC8KAB2_2N0AAAFrG9kBr5h5",
"buckets": [
"0"
],
"buyer": {
"accountID": "patricia@test.intershop.de",
"customerNo": "Patricia",
"email": "patricia@test.intershop.de",
"firstName": "Patricia",
"lastName": "Miller",
"secondName": "Magdalena",
"title": "Ms.",
"userNo": "patricia"
},
"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"
}
}
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.
{
"orderCreation": {
"status": "CONTINUE",
"redirect": {
"status": "SUCCESS",
"parameters" : [
{
"name": "transactionID",
"value": "id from provider"
}
]
}
}
}
{
"data": {
"basket": "oC8KAB2_2N0AAAFrG9kBr5h5",
"buckets": [
"0"
],
"buyer": { ... },
"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).
Order Creation States
| Order Creation Status | Stop Action | Info Code | Order Status | Payment Status | Note |
| COMPLETED | NEW | AUTHORIZED CAPTURED | Final state. Order was created. | ||
| ROLLED_BACK | order.cancelled.info | PAYMENT_CANCELLED | AUTHORIZATIONVOIDED | The 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. | |
| STOPPED | ExitReason = redirect_urls_required | order.creation_stopped.info | PENDING | PENDING | Set URLs for redirecting back from the PSP to the shop. |
| STOPPED | RedirectUrl available | PENDING | PENDING | Redirect user to provided URL. When returning, write data from response. | |
| STOPPED | ExitReason = waiting_for_pending_payments | order.creation_stopped.info | PENDING | AUTHORIZED (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. |