How to add the payment transaction status in order placed by using Demandware OCAPI?

Question

I'm developing API for the mobile app of e-commerce website which is on Demandware. I am using the OCAPI 18.8 to place an order and send the payment details to third-party payment processor which is Vantiv. I get the transaction ID and response code from Vantiv and want to update my order to store these payment transaction details into my order. But I could not find any resource in OCAPI which let me add the transaction Id and response code received from Vantiv. Below is the order which I have placed through OCAPI:

{
"_v": "18.8",
"_type": "order",
"_resource_state": "xyz",
"adjusted_merchandize_total_tax": 0,
"adjusted_shipping_total_tax": 0,
"billing_address": {
    "_type": "order_address",
    "city": "Boston",
    "country_code": "US",
    "first_name": "John",
    "full_name": "John Martin",
    "id": "xyz",
    "last_name": "Martin"
},
"channel_type": "storefront",
"confirmation_status": "not_confirmed",
"created_by": "Customer",
"creation_date": "2018-11-20T10:37:58.055Z",
"currency": "USD",
"customer_info": {
    "_type": "customer_info",
    "customer_id": "xyz",
    "customer_name": "Ammar Shahbaz",
    "customer_no": "xyz"
},
"customer_name": "Ammar Shahbaz",
"export_status": "not_exported",
"last_modified": "2018-11-20T10:37:58.376Z",
"merchandize_total_tax": 0,
"notes": {
    "_type": "simple_link",
    "link": "link"
},
"order_no": "123",
"order_token": "xyz",
"order_total": 299.8,
"payment_instruments": [
    {
        "_type": "order_payment_instrument",
        "amount": 299.8,
        "payment_card": {
            "_type": "payment_card",
            "card_type": "Visa",
            "credit_card_expired": false,
            "expiration_month": 1,
            "expiration_year": 2021,
            "holder": "John Doe",
            "masked_number": "************4240",
            "number_last_digits": "4240"
        },
        "payment_instrument_id": "xyz",
        "payment_method_id": "CREDIT_CARD"
    }
],
"payment_status": "not_paid",
"product_items": [
    {
        "_type": "product_item",
        "adjusted_tax": 0,
        "base_price": 149.9,
        "bonus_product_line_item": false,
        "gift": false,
        "item_id": "xyz",
        "item_text": "Long Sleeve Sequin Shift Dress",
        "price": 299.8,
        "price_after_item_discount": 299.8,
        "price_after_order_discount": 299.8,
        "product_id": "xyz",
        "product_name": "Dress",
        "quantity": 2,
        "shipment_id": "xyz",
        "tax": 0,
        "tax_basis": 299.8,
        "tax_class_id": "xyz",
        "tax_rate": 0,
        "c_cost": 25.17,
        "c_finalSale": false,
        "c_outlet": false,
        "c_taxClassID": "xyz"
    }
],
"product_sub_total": 299.8,
"product_total": 299.8,
"shipments": [
    {
        "_type": "shipment",
        "adjusted_merchandize_total_tax": 0,
        "adjusted_shipping_total_tax": 0,
        "gift": false,
        "merchandize_total_tax": 0,
        "product_sub_total": 299.8,
        "product_total": 299.8,
        "shipment_id": "xyz",
        "shipment_total": 299.8,
        "shipping_address": {
            "_type": "order_address",
            "city": "Boston",
            "country_code": "US",
            "first_name": "John",
            "full_name": "John Martin",
            "id": "xyz",
            "last_name": "Martin"
        },
        "shipping_method": {
            "_type": "shipping_method",
            "description": "Order received within 5-8 business days",
            "id": "xyz",
            "name": "Standard",
            "price": 0,
            "shipping_promotions": [
                {
                    "_type": "shipping_promotion",
                    "callout_msg": "Free shipping on U.S. orders of $125+",
                    "link": "link",
                    "promotion_id": "xyz",
                    "promotion_name": "Free Shipping With $125 Purchase"
                }
            ],
            "c_BxFlatrateFlag": false,
            "c_IsBorderlinxMethod": false
        },
        "shipping_status": "not_shipped",
        "shipping_total": 0,
        "shipping_total_tax": 0,
        "tax_total": 0
    }
],
"shipping_items": [
    {
        "_type": "shipping_item",
        "adjusted_tax": 0,
        "base_price": 0,
        "item_id": "xyz",
        "item_text": "Shipping",
        "price": 0,
        "price_after_item_discount": 0,
        "shipment_id": "xyz",
        "tax": 0,
        "tax_basis": 0,
        "tax_class_id": "xyz",
        "tax_rate": 0
    }
],
"shipping_status": "not_shipped",
"shipping_total": 0,
"shipping_total_tax": 0,
"site_id": "site name",
"status": "created",
"taxation": "net",
"tax_total": 0

}

I have tried this resource

Patch /orders/{order_no}/payment_instruments/{payment_instrument_id} 
{
 "amount" : 299.8,
 "payment_card" : {
                 "number":"424459xxxxxx4240",
                 "security_code":"121",
                 "holder":"John Martin",
                 "card_type":"Visa",
                 "expiration_month":1,
                 "expiration_year":2021
                },
"payment_method_id" : "CREDIT_CARD",
"c_PaymentProcessor": "VANTIV_CREDIT",
"c_paymentTransaction": {
  "custom": { 
    "litleAFTresponse": "Approved",
    "litleAFTTxnId": "8283868xxx8288282"
  }
}

}

to update my order but no success. Please let me know if you have any suggestion. Thanks.

Answer 1

If you have payment auth occurring outside of commerce cloud for some reason, you may be able to handle things in custom request document attributes. Note that there's an option to skip 'authorization' in CC by the skip_authorization parameter. eg:

POST /shop/v19_3/orders/00000027/payment_instruments?skip_authorization=true HTTP/1.1
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX 
Content-Type: application/json
{
  "amount": 49.99,
  "payment_method_id": "MY_PAYMENT_METHOD",
  "c_payment_token": "tokenvaluehere==",
  "c_payment_status": "payment_status"
}

Then within your dw.ocapi.shop.order.payment_instrument.afterPOST you could add attributes to the Order's PaymentInstrument via the B2C API methods which are accessible via the callback's order parameter.

You'll want to check in the beforePOST hook to ensure that the c_payment_status param is an acceptable value and if not return a Status.ERROR type of status object. Then you can actually save the properties in the afterPOST hook where the objects you'll need are already created.

For example:

exports.paymentInstrumentAfterPOST = function(order, paymentInstrumentRequest) {
  const PaymentTransaction = require('dw/order/PaymentTransaction');
  const Status = require('dw/system/Status');
  const Transaction = require('dw/system/Transaction');
  let methodId = paymentInstrumentRequest.payment_method_id;
  let instruments = order.getPaymentInstruments(methodId);
  let instrument = instruments[0]; // FIXME you should actually iterate over this instead; just for demo
  let paymentTransaction =  instrument.getPaymentTransaction();

  Transaction.begin();
  paymentTransaction.setTransactionID(paymentInstrumentRequest.c_payment_token);
  paymentTransaction.setType(PaymentTransaction.TYPE_AUTH);

  Transaction.commit();

  return new Status(Status.OK);
}

For more info on customizing the payment flow, see the Orders resource documentation

Disclaimer this is all code written free-hand in StackOverflow's answer form. I have not validated that this will actually run, but I hope it provides direction.

Answer 2

Internally in commerce cloud the below method call sets the transaction id: paymentInstrument.paymentTransaction.setTransactionID(anTransactionId) so your assumption is correct. This field is however not exposed in the shop API. From the documentation is is clear that the authorization of the payment should be triggered by commerce cloud. this is a security constraint. It is possible to customize the API to circumvent this limitation.

Answer 3

The platform itself has some internal workflows that you must follow step by step to complete an order via OCAPI Rest Api. You should follow the step by step workflow or if you don't find it ask your DW architect to guide you.

Answer 4

As of today, the platform provides a better way to handle this requirement. Under DATA API Endpoints you have now several entires to update overall order status, payment, shipment, or even shipping address. More details under official release notes:

You can now use Data API endpoints to update orders in server-to-server use cases, such as when an order management system or payment provider initiates a change.

Use new PUT commands to update the different types of order statuses.

PUT /sites/{site_id}/orders/{order_no}/confirmation_status 
PUT /sites/{site_id}/orders/{order_no}/export_status 
PUT /sites/{site_id}/orders/{order_no}/external_status 
PUT /sites/{site_id}/orders/{order_no}/payment_status 
PUT /sites/{site_id}/orders/{order_no}/shipping_status 
PUT /sites/{site_id}/orders/{order_no}/status 

Use a new PUT command to update an order’s shipping address.

PUT /sites/{site_id}/orders/{order_no}/shipments/{shipment_id}/shipping_address

Use new PATCH commands to update order and payment attributes.

PATCH /sites/{site_id}/orders/{order_no} 
PATCH /sites/{site_id}/orders/{order_no}/payment_instruments/{payment_instrument_id}
PATCH /sites/{site_id}/orders/{order_no}/payment_instruments/{payment_instrument_id}/transaction

source: https://help.salesforce.com/articleView?id=sf.b2c_20_2_W6833203_ocapi_order_update_endpoints_as.htm&type=5