Checkout resource - process orders and stage pending transactions

This resource allows you to process orders through the standard website checkout process, or stage / retrieve pending transactions.

Orders that are placed will execute just like normal website orders. It will:

Create the order & orderlines
Send an email receipt to the specified email address
Send an order notification to the merchant
Process any other aspects of the website's standard order processing
Return the order details

Prior to using this resource, you should have added items into a shopping cart.

The resource also provides functionality to stage pending transactions. This should be used with any multi-stage checkout process - e.g. when someone needs to complete payment via a 3rd party payment page. In this case you should initially stage the transaction which essentially keeps a full record of the users session, cart & checkout details. If for some reason the order then fails, or the user doesn't complete the rest of the process, the merchant will be able to access and optionally restore this order through the "abandoned orders" area of their merchant ecommerce tools.

The following methods are supported by this resource:

a PUT request will save a session as a pending transaction but not process the order, allowing you to process a payment, before POSTing back to complete the transaction. After saving the pending transaction, an order_id identifying the transcation will be returned in the response. A number of payment_option elements will provide the available payment methods to complete the order - by redirecting the user to one of these links they will be taken through the necessary steps to pay for the order (eg entering a credit card etc)
a POST request can either complete a pending transaction (if a order_id is passed as the record identifier), or process a complete order from scratch (in which case it will create a pending transcation, and then complete it in the same operation. Either way, a POST will result in a completed order, and will return details of the processed order.
a GET request has not been implemented, but eventually will retrieve the details of a specified pending transcation. If you have a need for this, please contact support@zeald.com to let us know.
a DELETE request will remove a pending transaction (if a valid order_id is specified)

Processing an order

You can process an order in 1 or 2 steps.

If you just want to check out the current cart in 1 step, POST your checkout XML data through to this resource.
If you want to stage the order & process it in a different step (e.g. to send the user off to a payment page before completing the staged order), then send a PUT request with the order detail. This will respond will an order_id which you can use to complete the order at a later stage.
- To complete this order, simply POST the order_id back to this resource in the format https://mydomain.nz/API/V3/Checkout/$order_id and the order will process through the standard order routes, sending off any notifications, creating the order & lines etc.

Submitting checkout data

The following is an example of the XML expected to be received to stage or process a new order. Documentation is provided inline in comments - obviously the comments should not be part of your XML payload.

<ResultSet>
    <Checkout>

        <!-- The current user / primary contact / person placing the order -->
        <user>
            <fname>Peter</fname>
            <lname>Janson</lname>
            <company>Janson Ltd</company>

            <!-- Country code for the user -->
            <country>NZ</country>
            <address1>PO Box 901-188</address1>
            <address2>Mt Eden</address2>
            <city>Auckland</city>
            <zip>0442</zip>
            <phone>021 411 1111</phone>
            <email>peter.janson@janson.co.nz</email>
        </user>

        <!--
            A recipient node is completely optional and should only be submitted
            if the order should be delivered to a person or address that differs
            from the primary contact address.

            This current example indicates the order should be delivered to the
            same person, but with a different physical address.

            Note: we don't collect an email address for the recipient.
        -->
        <recipient>
            <fname>Peter</fname>
            <lname>Janson</lname>
            <company>Janson Ltd</company>
            <country>NZ</country>
            <address1>12 Perrington Close</address1>
            <address2>Mt Eden</address2>
            <city>Auckland</city>
            <zip>8383</zip>
            <phone>021 411 1111</phone>
        </recipient>

        <!--
            An optional supported delivery method. Supported delivery methods are
            presented to the shopping cart. If you do not pass in a delivery method
            here, it will default to a delivery method set with the shopping cart,
            failing back using the default shipping method for the specified country.
        -->
        <delivery_mode>UrbanRural</delivery_mode>

        <!--
            A supported payment method code. The code `internal` will sipmly process
            the order, expecting payment will be dealt with by your app.

            To get a list of supported payment methods, you currently will need to
            check the merchant administration tool for the website. If your app
            needs to do this programatically, contact us at support@zeald.com.
        -->
        <payment>internal</payment>

        <!--
            Optional notes against the order. Depending on how the website is
            configured, on some websites this is a 'Gift note'.
        -->
        <notes>Please deliver it around the side of the house to the back door.</notes>

        <!--
            Optional tags against the order.
        -->
        <tags>
            <tag>facebook</tag>
            <tag>foo-tag</tag>
        </tags>
    </Checkout>
</ResultSet>

Staging a pending transaction

To stage a pending transaction send a PUT request to /API/V3/Checkout/ with a checkout payload as documented above.

If your client does not support the PUT request method, you can optionally pass the special argument _method=PUT.

Your request will receive the following response:

<?xml version="1.0" encoding="utf-8" ?><rsp perform\
ed_at="Thu Aug 27 22:56:38 2020" session="ENorEmCFvzG8aRt" stat="ok" version="3.0">
   <order_id>2008272256387676</order_id>
   <payment_option name="directcredit" description="Direct Credit" internal="1" link="http://localhost:8097/payment_handler/x_op/pay/order_id/2008272256387676/payment_method/directcredit.html" />
   <payment_option name="postal" description="Cheque (Mail Order)" link="http://localhost:8097/payment_handler/x_op/pay/order_id/2008272256387676/payment_method/postal.html" />
   <payment_option name="po" description="Purchase Order" link="http://localhost:8097/payment_handler/x_op/pay/order_id/2008272256387676/payment_method/po.html" />
   <payment_option name="cod" description="Cash On Delivery" link="http://localhost:8097/payment_handler/x_op/pay/order_id/2008272256387676/payment_method/cod.html" />
   <success>1</success>
</rsp>

Completing a staged transaction

To complete a staged / pending transaction, you can POST to this resource, specifying the order_id - e.g. https://mydomain.nz/API/V3/Checkout/$order_id. Alternatively the order_id can be specified in the querystring: https://mydomain.nz/API/V3/Checkout?order_id=$order_id.

You can optionally update the payment method by passing method=$method as a querystring parameter. Additionally you can pass verify=1 at the same time, and this will perform additional validation to ensure the specified payment method is a valid 'internal' payment method - aka supports instant process without 3rd party payment pages.

XML response after completing the order

After you have POSTed to this resource to complete the order, you will receive a standard Receipt response which will provide you all the detail you need to present the processed order details to the user as a receipt.

See the Receipt resource documentation for more details.