Create Order Authorize

Warning

This documentation is for translated APIs and intended only for some implementations who have upgraded from a previous version of Order Management. Verify whether your implementation uses translated APIs before making this call, as you will experience errors if your tenant is not configured to use these. If your implementation is not configured to do so, then refer to the standard API documentation instead.

The Create Order Authorize API will reach out to the payment gateway that Kibo OMS is integrated with and create an authorization token for the payment information. That token will then need to be passed through the Create Order request as the “Authorization ID” parameter. Therefore, this call should be made before Create Order or other processing APIs.

This call does not support split orders, as the payment token is associated 1:1 with an Order ID. When an order is split, each of the resulting orders must have a separate authorization request.

Note that the request body and parameter schemas outlined in this guide are the exact same as in the previous version of OMS, as the Unified Commerce platform supports backwards compatibility for this API. The only change to this request is the format of the base endpoint, as shown in the below table. Remember to provide the x-vol-tenant key for authentication in the headers.

Production URL	https://{tenantId}-translation.mozu.com/api/v2/createOrder/authorize
Sandbox URL	https://{tenantId}-translation.sandbox.mozu.com/api/v2/createOrder/authorize
Supported Formats	JSON
HTTP Method	POST

Example

The example case creates an API call to authorize a payment that has the following properties:

External Cart ID 0123456
USD Credit Card payment

This guide will demonstrate how to put together each section of the request to build this order.

Required Parameters

These parameters are necessary for the Create Order API to return a successful response:

Parameter	Type	Description
externalCardID	string	The cart identifier from a third party. The minimum length is 1 and the maximum length is 255.
manufacturerID	integer	A unique identifier for a manufacturer. The minimum value is “1”.
catalogID	integer	The catalog number for the manufacturer. The minimum value is “0”.
currency	enum	An International Standards Organization Code for the order’s currency (USD, CAD, etc.).
paymentMethod	object	The payment method of the order. See the schema for all possible structures.
amount	number	The payment amount to authorize. The minimum value is “0”.
customer	object	The customer who is purchasing the order.

Optional Parameters

There are a few other optional parameters that can be included if needed:

Parameter	Type	Description
locale	enum	An Internet Engineering Task Force code identifying the location and language of the order. The default is “en-US”.
testOrder	boolean	Whether this should be treated as a test order. The default is “false”.
shippingAddress	object	The address for the order when it is shipped. See the schema for the complete structure.

Customer

These are the possible parameters available to create the Customer object. Only firstName, lastName, email, and phone1 are required.

Parameter	Type	Description
customerID	string	A unique identifier for the customer, usually an integer. The minimum length is 1.
firstName	string	The first name of the customer. The minimum length is 1 and the maximum length is 300.
lastName	string	The last name of the customer. The minimum length is 1 and the maximum length is 300.
email	string	The email address of the customer. The minimum length is 1 and the maximum length is 250.
phone1	string	The phone number of the customer. The minimum length is 1 and the maximum length is 20.
phone2	string	The secondary phone number of the customer. The maximum length is 20.
accountCreated	string	The date that the customer’s account was created. Supports date-time format.
active	enum	Whether a customer’s account is active (ACTIVE), inactive (INACTIVE), or frozen (FROZEN).
customData	array	The custom information for the customer. Custom data is key/value information that may vary in use depending on implementation needs.

This example demonstrates the Customer object that will be used in the authorize request.

"customer": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "John.Smith@kibocommerce.com",
    "password": null,
    "phone1": "4691111111",
    "active": null,
    "accountCreated": null
  },

Payment Method

There are several ways to build the payment method. This example only shows how to use one option (a standard credit card payment), while payments for gift cards, PayPal, and other methods will vary.

"paymentMethod": {
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "addressLine1": "111 Example St",
    "phone": "4691111111",
    "city": "San Luis Obispo",
    "state": "CA",
    "postalCode": "93401",
    "countryCode": "US",
    "latitude": null,
    "longitude": null,
    "company": null
  },
  "paymentType": "CC",
  "cardIssuer": "VI",
  "noOperationType": null,
  "cardNumber": "4111111111111111",
  "cardExpiration": "10-2019",
  "cardSecurityCode": "123",
  "payPalToken": null,
  "payPalPayerID": null,
  "paymentMethodToken": null,
  "authToken": null,
  "ccLastFour": null,
  "cardToken": null,
  "creditPlan": null,
  "creditPlanType": null,
  "retailerRef": null,
  "financeCode": null,
  "paymentMethodID": null
},

The Full Request

This is the entire request that will authorize order creation.

{
  "externalCartID": "0123456",
  "manufacturerID": 01010,
  "catalogID": 0,
  "currency": "USD",
  "locale": "en-US",
  "customer": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "John.Smith@kibocommerce.com",
    "password": null,
    "phone1": "4691111111",
    "active": null,
    "accountCreated": null
  },
  "paymentMethod": {
    "billingAddress": {
      "firstName": "John",
      "lastName": "Smith",
      "addressLine1": "111 Example St",
      "phone": "4691111111",
      "city": "San Luis Obispo",
      "state": "CA",
      "postalCode": "93401",
      "countryCode": "US",
      "latitude": null,
      "longitude": null,
      "company": null
    },
    "paymentType": "CC",
    "cardIssuer": "VI",
    "noOperationType": null,
    "cardNumber": "4111111111111111",
    "cardExpiration": "10-2019",
    "cardSecurityCode": "123",
    "payPalToken": null,
    "payPalPayerID": null,
    "paymentMethodToken": null,
    "authToken": null,
    "ccLastFour": null,
    "cardToken": null,
    "creditPlan": null,
    "creditPlanType": null,
    "retailerRef": null,
    "financeCode": null,
    "paymentMethodID": null
  },
  "amount": 2.00,
  "testOrder": true,
  "shippingAddress": {
    "addressID": null,
    "customerID": null,
    "firstName": "Alan",
    "lastName": "Gudiel",
    "addressLine1": "222 Test Example Dr",
    "phone": "97200000000",
    "city": "Petaluma",
    "state": "CA",
    "postalCode": "94954",
    "countryCode": "US",
    "fraudLock": null,
    "active": null,
    "latitude": null,
    "longitude": null,
    "company": null,
    "taxID": null,
    "isBilling": null,
    "isShipping": null
  }
}

The response will return the Order ID, Payment Method Token, and Auth Token. The authorization token is what should be used in the Create Order request.