Checking Out Purchases and Getting Checkout Data

The Checkout API provides endpoints for placing, updating and retrieving checkout information.

In order to create a checkout experience, we offer an endpoint that allows placing orders and an additional endpoint that allows retrieving and updating checkout information. The data exposed by the endpoints is based not only on the shopping cart that is being checked out but also on the customers themselves. For registered customers, the API provides their registered addresses as well as the applicable payment and shipment methods.

If necessary, checkout data can be updated each time additional checkout information is provided. For example, for the purposes of fraud protection, specific payment methods can be disallowed for certain delivery addresses. In this case, a second call may be necessary to perform verification of payment method restrictions.

Apart from that, the API also supports redirecting to third party websites for additional checkout procession. Such a possibility may be needed, for example, when a customer pays with the help of an external payment system. For this purpose, the API allows generating a payload in the format and with the data as required by the third party, as well as processing the response received from it.

It is the responsibility of the API Client to redirect to the third party web site, send the payload and receive it (if necessary). The API is only responsible for generating a redirect URL, as well as generating and processing the payloads.

Installation

For detailed information on the modules that provide the API functionality and related installation instructions, see Checkout API Feature Integration.

Checkout Workflow

There are three endpoints provided to implement checkout via the API:

  • /checkout-data - allows submitting checkout data as many times as you need. Using the endpoint, you can implement checkout steps in your Glue API client, perform verification steps and execute other operations that require multiple calls to complete. The endpoint does not allow placing an order.

    For usage information, see section Submitting Checkout Data.

  • /checkout - finalizes the checkout process and places an order. The cart is deleted automatically, and you cannot make any changes in the checkout data. Thus, the endpoint can be used for checkouts that can be performed in one pass or for finalizing a checkout after using /checkout-data.

    For usage information, see section Placing Orders.

    The endpoint also provides information on whether it is necessary to redirect the user to a third party page to complete the payment.

  • /order-payments - allows completing the payment with payment verification on a third party page.

    For usage information, see sections Redirecting the User for Payment Confirmation and Updating Payment Data.

A typical API Client workflow is as follows:

Submitting Checkout Data

To submit checkout data without order confirmation, you need to use the /checkout-data endpoint:

/checkout-data

Sample request: POST http://glue.mysprykershop.com/checkout-data

Request

A request should contain the ID of the customer's cart that is being checked out. All other fields are optional.

To submit a request, the customer needs to have at least one cart with products in it.

In your request, you can use the addresses stored in a customer's account rather than specify them explicitly. To do so, pass the address identifier as a part of the billingAddress or the shippingAddress fields.

The address identifiers will be available in the addresses field of the endpoint response. For details, see subsection Response.
You can also retrieve the IDs by querying the /customers/{{customer_reference}}/addresses endpoint. For details, see Managing Customers.

The following address parts are compulsory: salutation, firstName, lastName, address1, address2, zipCode, city, iso2Code. If you are using an address ID, you can pass dummy values for the address parts. When resolving the ID, they will be replaced with the actual values of the customer account.

User Identification

In order to access the endpoint, you need to identify the user whose cart you are checking out:

  • If you are checking out a cart of a registered user, you need to include the user's authorization token in the request.

    For details, see Authentication and Authorization.

  • If you are checking out a guest cart, you need to include the guest user identifier in the X-Anonymous-Customer-Unique-Id header.

    For details, see Managing Guest Carts.

You can also use the Accept-Language header to specify the locale.
Sample header:
[{"key":"Accept-Language","value":"de, en;q=0.9"}]
where de and en are the locales; q=0.9 is the user's preference for a specific locale. For details, see 14.4 Accept-Language.

Response

In case of a successful update, the endpoint responds with information that can help you fill in the missing checkout data, such as the customer's addresses, available payment and shipment methods, etc.

Possible Errors

Status Reason
400

Bad request. This error can occur due to the following reasons:

  • The POST data is incorrect;
  • Neither Authorization nor X-Anonymous-Customer-Unique-Id headers were provided in the request.
422 The checkout data is incorrect

Placing Orders

To finalize checkout and place an order, send a POST request to the following endpoint:

/checkout

Sample request: POST http://glue.mysprykershop.com/checkout

Request

A request should contain:

  • valid customer information (e.g. first name, last name, salutation etc);
  • payment and shipment methods (they should exist in the system);
  • valid shipping and billing addresses;
  • ID of the customer's cart that is being checked out.

To submit a request, the customer needs to have at least one cart with products in it.

By default, if the checkout is successful, the order is placed and the shopping cart is deleted automatically.

In your request, you can use the addresses stored in a customer's account rather than specify them explicitly. To do so, pass the address identifier as a part of the billingAddress or the shippingAddress fields.

The address identifiers will be available in the addresses field of the /checkout-data endpoint response. For details, see subsection Response.
You can also retrieve the IDs by querying the /customers/{{customer_reference}}/addresses endpoint. For details, see Managing Customers.

The following address parts are compulsory: salutation, firstName, lastName, address1, address2, zipCode, city, iso2Code. If you are using an address ID, you can pass dummy values for the address parts. The iso2Code must be a valid code, for example, DE. When resolving the ID, they will be replaced with the actual values of the customer account.

User Identification

In order to access the endpoint, you need to identify the user whose cart you are checking out:

  • If you are checking out a cart of a registered user, you need to include the user's authorization token in the request.

    For details, see Authentication and Authorization.

  • If you are checking out a guest cart, you need to include the guest user identifier in the X-Anonymous-Customer-Unique-Id header.

    For details, see Managing Guest Carts.

You can also use the Accept-Language header to specify the locale.
Sample header:
[{"key":"Accept-Language","value":"de, en;q=0.9"}]
where de and en are the locales; q=0.9 is the user's preference for a specific locale. For details, see 14.4 Accept-Language.

Response

The endpoint responds with the checkout information.

Among the attributes returned, there is orderReference that can be used to reference the associated order in the future.

Response Attributes:

Attribute* Type Description
orderReference String Specifies a reference that can be used to access the order in the future.
redirectUrl String Specifies a URL where the customer needs to be redirected to perform additional verification, if necessary.
isExternalRedirect Boolean Indicates whether the customer is redirected to an external URL.

*The attributes mentioned are all attributes in the response. Type and ID are not mentioned.

You can extend the response with the orders resource relationship in order to obtain detailed order information.

For detailed information and a list of attributes, see section Retrieving Specific Order.

Sample request: POST http://glue.mysprykershop.com/checkout?include=orders

Possible Errors

Status Reason
400

Bad request. This error can occur due to the following reasons:

  • The POST data is incorrect;
  • Neither Authorization nor X-Anonymous-Customer-Unique-Id headers were provided in the request.
422 The checkout data is incorrect

Redirecting the User for Payment Confirmation

When placing an order, you need to check the value of the redirectURL attribute. If the value is null or empty, this means that the payment method selected by the customer does not require additional verification. If verification is necessary, the attribute will contain a URL to redirect the customer to.

It is the responsibility of the API Client to redirect the customer to the page and capture the response. For information on how to process it, see information on the payment service provider's API.

The formats of the payloads used in the request and response to the third party page are defined by the respective Eco layer module that implements the interaction with the payment provider. For details, see section 3. Implement Payload Processor Plugin in Interacting with Third Parties via Glue API.

Updating Payment Data

If the user is redirected to a third-party page for payment verification, you need to update the payment with the payload received from the payment provider. To do so, post the payload to the following endpoint:

/order-payments

Sample request: POST http://glue.mysprykershop.com/order-payments

Request

Your request should contain the payload related to the order. The request can include an optional payment identifier, if necessary.

The identifier is specified in the orderReference attribute of the /checkout endpoint response.

Attributes

Attribute Type Required Description
paymentIdentifier String

Payment ID

The value of the payment identifier depends on the payment services provider plugin used to process the payment. For details, see section 3. Implement Payload Processor Plugin in Interacting with Third Parties via Glue API.

dataPayload Array

Payload received from the payment service provider

You can also use the Accept-Language header to specify the locale.
Sample header:
[{"key":"Accept-Language","value":"de, en;q=0.9"}]
where de and en are the locales; q=0.9 is the user's preference for a specific locale. For details, see 14.4 Accept-Language.

Response

If the request was successful, the endpoint will respond with a 201 Created status code and a new payload, if it is necessary to pass it to a third party provider. If there is no new payload, the dataPayload is null.

Response Attributes:

Attribute* Type Description
paymentIdentifier String

Payment ID

dataPayload Array

Payload

*The attributes mentioned are all attributes in the response. Type and ID are not mentioned.

Possible Errors

Status Reason
404 Order not found
422 Order payment is not updated

See also:

 

Last review date: July 26, 2019