Create Order Authorize
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.
Note that 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.
Version | 2.0 |
Call | https://integration.shopatron.com/api/v2/createOrder/authorize |
Supported Formats | JSON |
HTTP Method | POST |
Schema | https://integration.shopatron.com/api/v2/schema/createOrder/authorizeRequest.json |
The .json address above can be used to access the schema within Postman. An example use of the Create Order Authorize API follows below, or view the schema or the sample Postman Collection.
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
The Payment Method must be one of eleven options. This example only shows how to use one option (a standard credit card payment), so see the schema for descriptions of the other ten possibilities such as gift cards, PayPal, and so forth.
"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.