Orders Resource (Shop API 16.2)

Summary

Http Method Resource Description
POST /Orders Submits an order based on a prepared basket.

Note: If the basket has been submitted using Order Center (considered by it's client id) the channel type will be set to "Call Center". In case another channel type was set by a script before submitting the basket, the channel type will be reset to "Call Center" and a warning will be logged. The only considered value from the request body is basket_id.
GET /Orders/{Order_no} Gets information for an order.
POST /Orders/{Order_no}/Notes Adds a note to an existing order.
GET /Orders/{Order_no}/Notes Retrieves notes for an order.
POST /Orders/{Order_no}/Payment_instruments

Adds a payment instrument to an order. It is possible either to supply the full payment information or only a customer payment instrument id and amount. In case the customer payment instrument id was set all the other properties (except amount) are ignored and the payment data is resolved from the stored customer payment information. An attempt is made to authorize the order by passing it to the authorize or authorizeCreditCard hook.

Details:

  • The payment instrument is added with the provided details or the details from the customer payment instrument. The payment method must be applicable for the order see GET /baskets/{basket_id}/payment_methods, if the payment method is 'CREDIT_CARD' a payment_card must be specified in the request.
  • Order authorization:

    To authorize the order one of two possible customization hooks is called and an dw.order.OrderPaymentInstrument is passed as an input argument.

    Which hook is called?

    • If the request includes a payment_card or the dw.order.OrderPaymentInstrument contains a creditCardType the customization hook dw.order.payment.authorizeCreditCard is called. See dw.order.hooks.PaymentHooks.authorizeCreditCard(order : Order, paymentDetails : OrderPaymentInstrument, cvn : String) : Status.
    • Otherwise dw.order.payment.authorize is called. See dw.order.hooks.PaymentHooks.authorize(order : Order, paymentDetails : OrderPaymentInstrument) : Status.

    What is the dw.order.OrderPaymentInstrument input argument passed to the hook?

    • If the request contains a customer_payment_instrument_id the dw.order.OrderPaymentInstrument is copied from the customer payment instrument (An exception is thrown if none was found).
    • Otherwise the data from the request document is passed (payment_card or payment_bank_account etc. information).

    Note: the amount and the security_code (cvn) contained in the payment_card data will be propagated if available to dw.order.payment.authorizeCreditCard even if the dw.order.OrderPaymentInstrument is resolved from a customer payment instrument.

  • Customization hook dw.ocapi.shop.order.afterPostPaymentInstrument is called. The default implementation places the order if the order status is CREATED and the authorization amount equals or exceeds the order total. Placing the order (equivalent to calling dw.order.OrderMgr.placeOrder(order : Order) in the scripting API) results in the order being changed to status NEW and prepared for export.
PATCH /Orders/{Order_no}/Payment_instruments/{Payment_instrument_id}

Updates a payment instrument of an order and passes the order and updated payment instrument to the correct payment authorizeCreditcard or authorize hook.

Details:

  • The payment instrument is updated with the provided details. The payment method must be applicable for the order see GET /baskets/{basket_id}/payment_methods, if the payment method is 'CREDIT_CARD' a payment_card must be specified in the request.
  • Order authorization:

    To authorize the order one of two possible customization hooks is called and an dw.order.OrderPaymentInstrument is passed as an input argument.

    Which hook is called?

    • If the request includes a payment_card or the dw.order.OrderPaymentInstrument contains a creditCardType the customization hook dw.order.payment.authorizeCreditCard is called. See dw.order.hooks.PaymentHooks.authorizeCreditCard(order : Order, paymentDetails : OrderPaymentInstrument, cvn : String) : Status.
    • Otherwise dw.order.payment.authorize is called. See dw.order.hooks.PaymentHooks.authorize(order : Order, paymentDetails : OrderPaymentInstrument) : Status.

    What is the dw.order.OrderPaymentInstrument input argument passed to the hook?

    • If the request contains a customer_payment_instrument_id the dw.order.OrderPaymentInstrument is copied from the customer payment instrument (An exception is thrown if none was found).
    • Otherwise the data from the request document is passed (payment_card or payment_bank_account etc. information).

    Note: the amount and the security_code (cvn) contained in the payment_card data will be propagated if available to dw.order.payment.authorizeCreditCard even if the dw.order.OrderPaymentInstrument is resolved from a customer payment instrument.

  • Customization hook dw.ocapi.shop.order.afterPatchPaymentInstrument is called. The default implementation places the order if the order status is CREATED and the authorization amount equals or exceeds the order total. Placing the order (equivalent to calling dw.order.OrderMgr.placeOrder(order : Order) in the scripting API) results in the order being changed to status NEW and prepared for export.
DELETE /Orders/{Order_no}/Payment_instruments/{Payment_instrument_id} Removes a payment instrument of an order.
GET /Orders/{Order_no}/Payment_methods Gets the applicable payment methods for an existing order considering the whole order amount.

Submit Basket

Submits an order based on a prepared basket.

Note: If the basket has been submitted using Order Center (considered by it's client id) the channel type will be set to "Call Center". In case another channel type was set by a script before submitting the basket, the channel type will be reset to "Call Center" and a warning will be logged. The only considered value from the request body is basket_id.

Url

POST https://hostname:port/dw/shop/v16_2/orders

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Request Document

Basket

Response Document

Order

Header Parameters

Parameter Type Description Constraints
If-Match String The ETag header value contained in the server response.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 GiftCertificateCreationException   Thrown if a failure during the creation of a gift certificate for a gift certificate item.
400 InvalidBasketIdException   Indicates that the basket id in the request body is null or empty.
400 EmptyShippingAddressException

shipmentId (String)

Indicates an empty shipping address.
400 InvalidShippingAddressException

shipmentId (String)

Indicates an invalid shipping address.
400 InvalidCouponCodeException

status (Status)

Indicates an invalid coupon code.
400 MissingShippingMethodIdException

shipmentId (String)

Indicates a missing shipping method.
400 InvalidShippingMethodIdException

shippingMethodId (String)

Indicates an invalid shipping method.
400 EmptyBillingAddressException   Indicates an empty billing address.
400 InvalidBillingAddressException   Indicates an invalid billing address.
400 MissingPaymentMethodIdException   Indicates a missing payment method.
400 InvalidPaymentMethodException

paymentMethodId (String)

Indicates that the payment method is invalid.
400 InvalidProductItemException

productId (String)

Indicates an invalid product item.
400 InvalidProductOptionItemException

optionId (String)

Indicates that an option with the specified option id is unknown.
400 InvalidProductOptionValueItemException

optionValueId (String)

optionId (String)

Indicates that an option with the specified option value id is unknown.
400 InvalidProductOptionItemPriceException

optionId (String)

Indicates an invalid product option item price.
400 ProductItemNotAvailableException

productId (String)

quantity (Decimal)

Thrown if a product item is not available.
400 InvalidCustomerException   Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT token, not relevant when using OAuth.
404 BasketNotFoundException

basketId (String)

Indicates that the basket with the given basket id is unknown.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.order.afterPOST

afterPOST (order : Order ) : Status

The function is called after an order was created from the basket.

Parameters:
order - the order that was created for the basket
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.order.beforePOST

beforePOST (basket : Basket ) : Status

The function is called before an order is created for the basket.

Parameters:
basket - the basket based on which the order is created
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
POST /dw/shop/v16_2/orders
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
If-Match: 6d762a1ad4888de31dc1a245444f084a4846c01d7e36cd09dc183adaa6fdb647
Content-Type: application/json

{
  "basket_id" : "cdxEQiWbNVZZaaaadhKBc35gtp"
}


# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
ETag: 125e1319918776a043fcef2b0e2fce7906abbdea7f5f2f1908ff0ba0fc46de88
Content-Type: application/json;charset=UTF-8

{
   "_v" : "16.2",
   "adjusted_merchandize_total_tax" : 0.05,
   "adjusted_shipping_total_tax" : 0.00,
   "billing_address" : {
      "city" : "Boston",
      "country_code" : "US",
      "first_name" : "Jeff",
      "full_name" : "Jeff Lebowski",
      "last_name" : "Lebowski",
      "c_strValue" : "cTest"
   },
   "creation_date" : "2014-11-06T13:36Z",
   "currency" : "USD",
   "customer_info" : {
      "customer_no" : "jlebowski",
      "email" : "[email protected]"
   },
   "merchandize_total_tax" : 5.00,
   "order_no" : "00000101",
   "order_token" : "XizrH5hY1vB-Mxno-zfoCqTkegl3y7_OrRPGNZFlYG8",
   "order_total" : 1.06,
   "payment_instruments" : [
      {
         "amount" : 1.00,
         "payment_bank_account" : {
            "drivers_license_last_digits" : "ense",
            "drivers_license_masked" : "**************ense",
            "number_last_digits" : "mber",
            "number_masked" : "*************mber"
         },
         "id" : "cdKCIiWbNVndQaaadhlSa35gtp",
         "payment_card" : {
            "card_type" : "testVisa",
            "credit_card_expired" : false,
            "expiration_month" : 4,
            "expiration_year" : 2018,
            "holder" : "TestPerson",
            "number_last_digits" : "mber",
            "number_masked" : "**********mber"
         },
         "payment_method_id" : "OCAPI_Payment_Simple"
      }
   ],
   "product_items" : [
      {
         "adjusted_tax" : 5.00,
         "base_price" : 16.29,
         "bonus_product_line_item" : false,
         "item_text" : "Simple Product",
         "price" : 16.29,
         "price_after_item_discount" : 16.29,
         "price_after_order_discount" : 1.00,
         "product_id" : "SimpleProduct",
         "product_name" : "Simple Product",
         "quantity" : 1.00,
         "tax" : 5.00,
         "tax_basis" : 16.29,
         "tax_class_id" : null,
         "tax_rate" : 0.05,
         "item_id" : "cdHBEiWbNV9ZcaaadhrCk35gtp",
         "c_strValue" : "Test"
      }
   ],
   "product_sub_total" : 16.29,
   "product_total" : 1.00,
   "shipments" : [
      {
         "id" : "me",
         "shipping_address" : {
            "city" : "Boston",
            "country_code" : "US",
            "first_name" : "Jeff",
            "full_name" : "Jeff Lebowski",
            "last_name" : "Lebowski",
            "c_strValue" : "cTest"
         },
         "shipping_method" : {
            "description" : {
               "default" : "The base shipping method."
            },
            "id" : "BaseShippingMethod",
            "name" : {
               "default" : "Base Shipping Method"
            },
            "price" : 0.01,
            "c_somestring" : "ShippingMethod String Value"
         }
      }
   ],
   "shipping_items" : [
      {
         "adjusted_tax" : 0.00,
         "base_price" : 0.01,
         "item_text" : "Shipping",
         "price" : 0.01,
         "price_after_item_discount" : 0.01,
         "shipment_id" : "me",
         "tax" : 0.00,
         "tax_basis" : 0.01,
         "tax_class_id" : "DefaultTaxClass",
         "tax_rate" : 0.05,
         "item_id" : "devgoiWbNVc92aaadhrSk35gtp"
      }
   ],
   "shipping_total" : 0.01,
   "shipping_total_tax" : 0.00,
   "status" : "created",
   "tax_total" : 0.05,
   "c_strValue" : "before submit basket",
   "c_textValue" : "after submit basket"
}


# in case of validation failure:

RESPONSE:
HTTP/1.1 404 NOT FOUND
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache,no-store,must-revalidate

{
   "_v" : "16.2",
   "fault" : {
      "type" : "BasketNotFoundException",
      "message" : "No basket with id '123' found."
   }
}

Get Order

Gets information for an order.

Url

GET https://hostname:port/dw/shop/v16_2/orders/{order_no}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Response Document

Order

Path Parameters

Parameter Type Description Constraints
order_no String the order number minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 OrderNotFoundException

orderNumber (String)

Indicates that the order with the given order number is unknown.

Sample

REQUEST:
GET /dw/shop/v16_2/orders/1234567890 HTTP/1.1
Host: example.com
Cookie: dwsid=tYlzC3YbZNo13dV5XS4OGzg0wClZGz4yThXHrvEZNUlT2ohYzMFyPJin5cW0wleUaxMnraXcEbg4mnymdroMlA==;
        dwanonymous_9727b83e8e864fa4b6902a37bc70a12d=bcdlZDxB7h5YakHw3p1ZTDPihp;
        dwsecuretoken_9727b83e8e864fa4b6902a37bc70a12d=5Kx5-2P7jj5WoxeTiWwHNBJ6QV39Io5SNA==
Content-Type: application/json; charset=UTF-8

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
ETag: y4ad025da50d1af6cac62e86de2b13def45ead81ffb01c407dad2dc4bfd438kl
Cache-Control: max-age=0,no-cache,no-store,must-revalidate

{
  "_v":"16.2",
  "_type":"order",
  "creation_date":"2014-06-15T04:02Z",
  "customer_info":{
    "email":"[email protected]"
  },
  "currency":"USD",
  "order_no":"1234567890",
  "order_price_adjustments":[{
    "promotion_id": "10$ off",
    "promotion_link": "https://example.com/dw/shop/v16_2/promotions/10_bugs_off",
    "item_text": "10$ off",
    "price": -10.00
  }],
  "order_token":"8dewokhrqwcdkjs83-46sjfdnbswr982nf63ks0sm-fnk23y6",
  "order_total":101.00,
  "payment_instruments" : [
  {
    "payment_instrument_id" : "ce6QR9aaabmakaaadf1KdLcXoH",
    "etag" : "4d48d1ec18cd88c046f889ff3da6ce7915554a88493d597de59cda31b49707d8",
    "payment_method_id" : "CREDIT_CARD",
    "payment_card" : 
    {
      "card_type" : "Visa",
      "expiration_month" : 12,
      "expiration_year" : 2018,
      "holder" : "Jeff Lebowski",
      "masked_number" : "************1111",
    },
    "amount" : 0.00
  }],
  "product_items":[{
    "product_id":"123",
    "item_text": "Product foo",
    "quantity":2.00,
    "product_name":"foo",
    "base_price":30.00,
    "price":60.00
  },
  {
    "product_id":"456",
    "item_text": "Product foo",
    "quantity":1.00,
    "product_name":"bar",
    "base_price":40.00,
    "price":40.00,
    "price_adjustments":[{
      "promotion_id": "10% off",
      "promotion_link": "https://example.com/dw/shop/v16_2/promotions/10_percent_off",
      "item_text": "10% off",
      "price": -4.00
    }]
  }],
  "product_sub_total":96.00,
  "product_total":86.00,
  "shipping_total":5.00,  
  "shipments":[{
    "id":"default",
    "shipping_address":{
      "salutation":"",
      "title":"",
      "company_name":"",
      "first_name":"",
      "second_name":"",
      "last_name":"",
      "postal_code":"",
      "address1":"",
      "address2":"",
      "city":"",
      "post_box":"",
      "country_code":"",
      "state_code":"",
      "phone":"",
      "suffix":""
    },
    "shipping_method":{
      "id":"001",
      "name":"Ground",
      "description":"Order received within 7-10 business days"
    }}],
  "status":"created",
  "tax_total":9.10
}

# in case of failure:
 
RESPONSE:
HTTP/1.1 404 Requested resource not found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v":"16.2",
  "_type":"fault",
  "fault":{
    "type":"NotFoundException",
    "message":"No order with number '1234567890' found."
  }
}

Add a Note to an Order

Adds a note to an existing order.

Url

POST https://hostname:port/dw/shop/v16_2/orders/{order_no}/notes

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Request Document

Note

Response Document

Order

Path Parameters

Parameter Type Description Constraints
order_no String The id of the order to be modified. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 OrderNotFoundException

orderNumber (String)

Thrown if the order with the given order number is unknown.

Sample

#
# Example: Add a note to an order
#
REQUEST:
POST /dw/shop/v16_2/orders/cdcM6iWbN5jyIaaadh5thrJrYj/notes
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json; charset=UTF-8

{
  "subject" : "this is an example subject",
  "text" : "This is a note because the customer was not very happy."
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
ETag: eaed36b37b7ba3f9f4550d9f76754fe58f2274244cc0b387e6820cae69c9c86e
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
   "_v" : "16.2",
   "_type" : "order",
...
   "notes" : { 
       "link" : "https://www.example.com/dw/shop/v16_2/orders/cdcM6iWbN5jyIaaadh5thrJrYj/notes"
    }
...
}

Get Notes from an Order

Retrieves notes for an order.

Url

GET https://hostname:port/dw/shop/v16_2/orders/{order_no}/notes

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Response Document

NotesResult

Path Parameters

Parameter Type Description Constraints
order_no String The id of the order from which you want to retrieve notes. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 OrderNotFoundException

orderNumber (String)

Thrown if the order with the given order number is unknown.

Sample

REQUEST:
GET /dw/shop/v16_2/orders/cdcM6iWbN5jyIaaadh5thrJrYj/notes HTTP/1.1
Host: example.com
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Length: 158
{
   "_v" : "16.2",
   "_type" : "notes_result",
   "notes" : 
   [
      {
         "subject" : "Unhappy customer",
         "text" : "The customer was not very happy due to a delay."
      },
      {
         "subject" : "Happy customer",
         "text" : "The customer is already happy!"
      }
   ]
}

Add Payment Instrument to Order

Adds a payment instrument to an order. It is possible either to supply the full payment information or only a customer payment instrument id and amount. In case the customer payment instrument id was set all the other properties (except amount) are ignored and the payment data is resolved from the stored customer payment information. An attempt is made to authorize the order by passing it to the authorize or authorizeCreditCard hook.

Details:

Url

POST https://hostname:port/dw/shop/v16_2/orders/{order_no}/payment_instruments

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Request Document

OrderPaymentInstrumentRequest

Response Document

Order

Path Parameters

Parameter Type Description Constraints
order_no String the order number minLength=1

Header Parameters

Parameter Type Description Constraints
If-Match String the ETag header value contained in the server response  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidOrderNumberException   Indicates that the given order number is invalid.
400 InvalidPaymentMethodIdException

paymentMethodId (String)

Indicates that the provided payment method is invalid or not applicable.
404 OrderNotFoundException

orderNumber (String)

Indicates that the order with the given order number is unknown.
404 PaymentInstrumentNotFoundException

type (String)

paymentInstrumentId (String)

Indicates that a customer payment instrument could not be resolved based on the provided customer payment instrument id.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.order.afterPostPaymentInstrument

afterPostPaymentInstrument (basket : Basket , paymentInstrument : BasketPaymentInstrumentRequest ) : Status

The function is called after payment instrument adding to a basket.

Parameters:
basket - the basket based on which the order is created
paymentInstrument - the payment instrument added to the basket
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.order.beforePostPaymentInstrument

beforePostPaymentInstrument (basket : Basket , paymentInstrument : BasketPaymentInstrumentRequest ) : Status

The function is called before payment instrument adding to a basket.

Parameters:
basket - the basket based on which the order is created
paymentInstrument - the payment instrument to be added to the basket
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.order.validateOrder

validateOrder (order : Order ) : Status

Validate an order after the order has been updated.

The hook is called outside a database transaction, so modifications to the order are not possible. Allows the addition of custom flashes to convey information to the client.

Example showing addition of flashes:

       exports.validateBasket = function() {
         order.addFlash(   {type:"PaymentAuthorizationFailure",
                     message:"Order was not successfully authorized.",
                        path:"authorizations",
                     details:{ "result":"reject", "reason":"invalid_credit_card"}});
       
Parameters:
order - the modified order
Returns:
a non-null Status ends the hook execution
dw.order.payment.authorize

authorize (order : Order , paymentDetails : OrderPaymentInstrument ) : Status

Custom payment authorization - modify the order as needed.
  • Prerequisite: An order has been created using the data api or via the storefront.
  • Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this).
  • Return Status.ERROR: Order is held, authorization needs to be repeated.
Parameters:
order - the order
paymentDetails - specified payment details
Returns:
  • Status.OK successful authorization.
  • Status.ERROR authorization failed.
dw.order.payment.authorizeCreditCard

authorizeCreditCard (order : Order , paymentDetails : OrderPaymentInstrument , cvn : String ) : Status

Custom payment authorization of a credit card - modify the order as needed.
  • Prerequisite: An order has been created using the data api or via the storefront.
  • Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this).
  • Return Status.ERROR: Order is held, authorization needs to be repeated.
Parameters:
order - the order
paymentDetails - specified payment details
cvn - the credit card verification number
Returns:
  • Status.OK successful authorization.
  • Status.ERROR authorization failed.

Sample

REQUEST:
POST /shop/v16_2/orders/00000027/payment_instruments
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
If-Match:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335 
Content-Type: application/json
{
  "amount": 2,
  "payment_card": {
    "number": "4111111111111111",
    "security_code": "112",
    "holder": "Ed Smith",
    "card_type": "Visa",
    "expiration_month": 2,
    "expiration_year": 2022
  },
  "payment_method_id": "CREDIT_CARD"
}
# in case of success

RESPONSE:
HTTP/1.1 200 OK
Content-Length:124 
ETag:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335§ 
Content-Type:application/json;charset=UTF-8

{
{
   "_v" : "16.2",
   "_type" : "order",
...
   "order_no" : "00000021",
...
   "payment_instruments" : 
   [
      
      {
         "_type" : "order_payment_instrument",
         "amount" : 2.00,
         "etag" : "175c697bbfd2f33c9fc88c3469d9a7892ed1821cd2293cf2f91457415e614e24",
         "payment_card" : 
         {
            "_type" : "payment_card",
            "card_type" : "Visa",
            "credit_card_expired" : false,
            "credit_card_token" : "00000021-2",
            "expiration_month" : 2,
            "expiration_year" : 2022,
            "holder" : "Ed Smith",
            "masked_number" : "***********1111",
            "number_last_digits" : "1111"
         },
         "payment_method_id" : "CREDIT_CARD",
         "payment_instrument_id" : "cdZnraOu6bcqwaaadlW5ROJu9Y",
      }
   ],
...
}

Updates Payment Instrument of Order

Updates a payment instrument of an order and passes the order and updated payment instrument to the correct payment authorizeCreditcard or authorize hook.

Details:

Url

PATCH https://hostname:port/dw/shop/v16_2/orders/{order_no}/payment_instruments/{payment_instrument_id}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Request Document

OrderPaymentInstrumentRequest

Response Document

Order

Path Parameters

Parameter Type Description Constraints
order_no String the order number minLength=1
payment_instrument_id String the id of the payment instrument to be updated minLength=1

Header Parameters

Parameter Type Description Constraints
If-Match String the ETag header value contained in the server response  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidPaymentMethodIdException

paymentMethodId (String)

Indicates that the provided payment method is invalid or not applicable.
404 OrderNotFoundException

orderNumber (String)

Indicates that the order with the given order number is unknown.
404 PaymentInstrumentNotFoundException

paymentInstrumentId (String)

Indicates that the payment instrument with the given payment instrument number is unknown.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.order.afterPatchPaymentInstrument

afterPatchPaymentInstrument (basket : Basket , paymentInstrument : OrderPaymentInstrument , paymentInstrumentRequest : BasketPaymentInstrumentRequest ) : Status

The function is called after updating a payment instrument of a basket.

Parameters:
basket - the basket based on which the order is created
paymentInstrument - the updated payment instrument
paymentInstrumentRequest - the new payment instrument data
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.order.beforePatchPaymentInstrument

beforePatchPaymentInstrument (basket : Basket , paymentInstrument : OrderPaymentInstrument , newPaymentInstrument : BasketPaymentInstrumentRequest ) : Status

The function is called before updating a payment instrument of a basket.

Parameters:
basket - the basket based on which the order is created
paymentInstrument - the payment instrument to be updated
newPaymentInstrument - the new payment instrument data
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.order.validateOrder

validateOrder (order : Order ) : Status

Validate an order after the order has been updated.

The hook is called outside a database transaction, so modifications to the order are not possible. Allows the addition of custom flashes to convey information to the client.

Example showing addition of flashes:

       exports.validateBasket = function() {
         order.addFlash(   {type:"PaymentAuthorizationFailure",
                     message:"Order was not successfully authorized.",
                        path:"authorizations",
                     details:{ "result":"reject", "reason":"invalid_credit_card"}});
       
Parameters:
order - the modified order
Returns:
a non-null Status ends the hook execution
dw.order.payment.authorize

authorize (order : Order , paymentDetails : OrderPaymentInstrument ) : Status

Custom payment authorization - modify the order as needed.
  • Prerequisite: An order has been created using the data api or via the storefront.
  • Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this).
  • Return Status.ERROR: Order is held, authorization needs to be repeated.
Parameters:
order - the order
paymentDetails - specified payment details
Returns:
  • Status.OK successful authorization.
  • Status.ERROR authorization failed.
dw.order.payment.authorizeCreditCard

authorizeCreditCard (order : Order , paymentDetails : OrderPaymentInstrument , cvn : String ) : Status

Custom payment authorization of a credit card - modify the order as needed.
  • Prerequisite: An order has been created using the data api or via the storefront.
  • Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this).
  • Return Status.ERROR: Order is held, authorization needs to be repeated.
Parameters:
order - the order
paymentDetails - specified payment details
cvn - the credit card verification number
Returns:
  • Status.OK successful authorization.
  • Status.ERROR authorization failed.

Sample

REQUEST:
PATCH /dw/shop/v16_2/orders/00000021/payment_instruments/cdZnraOu6bcqwaaadlW5ROJu9Y
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
If-Match:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335 
Content-Type: application/json
{
  "amount": 2,
  "payment_card": {
    "number": "4111111111111111",
    "security_code": "112",
    "holder": "Ed Smith",
    "card_type": "Visa",
    "expiration_month": 2,
    "expiration_year": 2022
  },
  "payment_method_id": "CREDIT_CARD"
}
# in case of success

RESPONSE:
HTTP/1.1 200 OK
Content-Length:124 
ETag:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335§ 
Content-Type:application/json;charset=UTF-8

{
{
   "_v" : "16.2",
   "_type" : "order",
...
   "order_no" : "00000021",
...
   "payment_instruments" : 
   [
      
      {
         "_type" : "order_payment_instrument",
         "amount" : 2.00,
         "etag" : "175c697bbfd2f33c9fc88c3469d9a7892ed1821cd2293cf2f91457415e614e24",
         "payment_card" : 
         {
            "_type" : "payment_card",
            "card_type" : "Visa",
            "credit_card_expired" : false,
            "credit_card_token" : "00000021-2",
            "expiration_month" : 2,
            "expiration_year" : 2022,
            "holder" : "Ed Smith",
            "masked_number" : "***********1111",
            "number_last_digits" : "1111"
         },
         "payment_method_id" : "CREDIT_CARD",
         "payment_instrument_id" : "cdZnraOu6bcqwaaadlW5ROJu9Y",
      }
   ],
...
}

Removes a Payment Instrument of an Order

Removes a payment instrument of an order.

Url

DELETE https://hostname:port/dw/shop/v16_2/orders/{order_no}/payment_instruments/{payment_instrument_id}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Response Document

Order

Path Parameters

Parameter Type Description Constraints
order_no String the order number minLength=1
payment_instrument_id String the id of the payment instrument to be updated minLength=1

Header Parameters

Parameter Type Description Constraints
If-Match String the ETag header value contained in the server response  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 OrderNotFoundException

orderNumber (String)

Indicates that the order with the given order number is unknown.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.order.validateOrder

validateOrder (order : Order ) : Status

Validate an order after the order has been updated.

The hook is called outside a database transaction, so modifications to the order are not possible. Allows the addition of custom flashes to convey information to the client.

Example showing addition of flashes:

       exports.validateBasket = function() {
         order.addFlash(   {type:"PaymentAuthorizationFailure",
                     message:"Order was not successfully authorized.",
                        path:"authorizations",
                     details:{ "result":"reject", "reason":"invalid_credit_card"}});
       
Parameters:
order - the modified order
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
DELETE /shop/v16_2/orders/00000029/payment_instruments/cdXTraOu6bXT6aaadll5tOJvce
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
If-Match:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335 

# in case of success

RESPONSE:
HTTP/1.1 200 OK
Content-Length:124 
ETag:01ea4f898d53428be312a8a857dec5794a2fa80cf9e5cc2d4560f5316c830335§ 
Content-Type:application/json;charset=UTF-8

{
{
   "_v" : "16.2",
   "_type" : "order",
...
   "order_no" : "00000021",
...
   "payment_instruments" : 
   [
      
      {
        ...
      }
   ],
...
}

Get Applicable Payment Methods for an Order

Gets the applicable payment methods for an existing order considering the whole order amount.

Url

GET https://hostname:port/dw/shop/v16_2/orders/{order_no}/payment_methods

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT token.
OAuth Authentication via OAuth token.

Response Document

PaymentMethodResult

Path Parameters

Parameter Type Description Constraints
order_no String the order number minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidCustomerException   Indicates that the customer assigned to the order does not match the verified customer represented by the JWT token, not relevant when using OAuth.
404 OrderNotFoundException

orderNumber (String)

Indicates that the order with the given order number is unknown.

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.order.payment_methods.afterGET

afterGET (order : Order , paymentMethods : PaymentMethodResult ) : Status

Called before returning the list of available payment methods to the customer. Allowing modifications of the result.

Parameters:
order - the order
paymentMethods - the available payment methods
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v16_2/orders/cdcM6iWbN5jyIaaadh5thrJrYj/payment_methods
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
If-Match: 6d762a1ad4888de31dc1a245444f084a4846c01d7e36cd09dc183adaa6fdb647
Content-Type: application/json

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Type: application/json;charset=UTF-8

{
   "_v" : "16.2",
   "_type" : "payment_method_result",
   "applicable_payment_methods" : 
   [
      {
         "_type" : "payment_method",
         "id" : "BANK_TRANSFER",
         "name" : "Bank Transfer"
      },
      {
         "_type" : "payment_method",
         "cards" : 
         [
            {
               "_type" : "payment_card_spec",
               "card_type" : "Visa",
               "checksum_verification_enabled" : true,
               "id" : "CREDIT_CARD.Visa",
               "name" : "Visa",
               "number_lengths" : 
               [
                  "13",
                  "16"
               ],
               "number_prefixes" : 
               [
                  "4"
               ],
               "security_code_length" : 3,
               "c_somestring" : "PaymentCard String Value"
            },
            {
               "_type" : "payment_card_spec",
               "card_type" : "Master",
               "checksum_verification_enabled" : true,
               "id" : "CREDIT_CARD.Master",
               "name" : "Master Card",
               "number_lengths" : 
               [
                  "16"
               ],
               "number_prefixes" : 
               [
                  "51-55"
               ],
               "security_code_length" : 3,
               "c_somestring" : "PaymentCard String Value"
            },
            ...
}

# in case of validation failure:

RESPONSE:
HTTP/1.1 404 NOT FOUND
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache,no-store,must-revalidate

{
   "_v" : "16.2",
   "fault" : 
   {
      "type" : "NotFoundException",
      "message" : "No order with id 'non_existing_order' found."
   }
}