- Previous: JSONP Response
- Up: Product Lookup API
- Next:
Commerce API with JWT Encryption
This document describes the steps needed to integrate with Walmart Checkout API(V2). Please note that this is a work in progress and is subject to change.
Checkout API Workflow
-
Partner will create an account on developer.walmartlabs.com and let Walmart API team know about their username for Mashery account.
-
Partner will provide order details in an JSON format that conforms to the JSON Schema document that Walmart provided to partner.
-
Partner will use Checkout Feed (http://api.walmartlabs.com/v1/feeds/checkoutV2?apiKey=<apikey>) daily to get all items available for checkout.
-
Products available for checkout to partner will exclude any Walmart.com Marketplace items, service plans, bundles and tires. Certain heavy items included in the catalog that are categorized as freight items will not be available for delivery to Alaska, Hawaii, and U.S. Protectorates like Puerto Rico and U.S. Virgin Islands. Walmart will use commercially reasonable efforts to identify such excluded items in the Checkout Feed API.
-
Until the development of separate APIs for cancellations and returns, they will be completed through a manual process
-
Daily and monthly reports will be shared via FTP with partner containing details of orders placed, orders shipped and cancellations. Month-end report will also contain details of commissions payable for the month. You need to provide us your FTP server location and credentials so that we can put the files on your server.
Dev Portal
You need to create an account on http://developer.walmartlabs.com and send us an email at affilops@wal-mart.com with your Mashery username. Walmart will then create a Checkout API package account for you.
Authentication
Before you can make actual Checkout calls, you will to get an OAuth token. This token is valid for 10 mins and you will have to get a new token after that. Here is a sample way to get your OAuth token:
curl -i -u '<Your API key>:<your API shared secret>' -d 'grant_type=client_credentials' https://api.walmartlabs.com/v2/qa/oauth2/token |
A typical response will look like:
HTTP/1.1 200 OK
Cache-Control: no-store
Content-Type: application/json;charset=UTF-8
Date: Tue, 18 Jun 2013 08:17:54 GMT
Server: Mashery Proxy
X-Mashery-Responder: prod-j-worker-us-west-1c-13.mashery.com
Content-Length: 116
Connection: keep-alive
{"token_type":"bearer","mapi":"z8snfepkm763xvg85ngt9jq6","access_token":"dr9r4uue4a4mewejyyhm5x8q","expires_in":600}
|
The access_token field in above response contains the OAuth token.
Headers
Every API call should have the following headers.
| Header | Value |
|---|---|
| X-Walmart-User-IP | Customer IPv4 address (Eg. 161.170.244.20) |
| X-Walmart-User-Device-Type | Customer Device Type. One of browser, mobile_web, batch,
iphone_app, ipad_app, android_app, mobile_other |
| X-Walmart-User-Agent | Customer User Agent (Eg. Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36) |
API Flow
Checkout occurs in 2 steps. The first step is the Prepare Order call which gives pricing/tax/shipping details of items sent in the request and returns back an id. The subsequent Place order call executes the order.
Prepare Order
There are 3 top level json objects: customerInfo, items and shippingInfo
Request:
curl -H "Authorization: Bearer dr9r4uue4a4mewejyyhm5x8q" -H "X-Walmart-User-IP: 127.0.0.1" -H "X-Walmart-User-Device-Type: browser" -H "X-Walmart-User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36" -d @prepare.json https://api.walmartlabs.com/v2/qa/order/prepare
prepare.json
{
"customerInfo": {
"firstName": "John",
"lastName": "Doe",
"email": "johndoe@gmail.com",
"phone": "6502150456"
},
"items": [
{
"itemId": "24074298",
"sellerId": 0,
"qty": 2
},
{
"itemId": "23554123",
"sellerId": 0,
"qty": 1
}
],
"shippingInfo": {
"fulfillmentType": "SHIPPING",
"fulfillmentOption": "S2H",
"shipMethod": "VALUE",
"address": {
"firstName": "Jane",
"lastName": "Doe",
"street1": "750 N Shoreline Blvd",
"street2": "#2",
"city": "Mountain View",
"stateOrProvinceCode": "CA",
"zip": "94043",
"countryCode": "USA",
"phone": "6502150456"
},
"addressValidationMode" : "STRICT"
}
}
|
fulfillmentType - only SHIPPING allowed
fulfillmentOption - only S2H allowed
shipMethod - possible values are STANDARD, EXPEDITED, RUSH and FREIGHT. Note - If an item is a freight item, Product lookup API (https://developer.walmartlabs.com/docs/read/Home) will return an attribute named “freight” and its value will be “true”, use ship method as FREIGHT.
addressValidationMode - Optional: STRICT or LENIENT. See below
Response:
{
"token": "31ce17ae-a9fe-4f60-aa08-8fac2bf4dd9d",
"items": [
{
"itemId": "24074298",
"sellerId": 0,
"qty": 2,
"unitPrice": 7.98,
"expectedShipTimestamp": 1412893800000,
"expectedDeliveryTimestamp": 1413325800000
},
{
"itemId": "23554123",
"sellerId": 0,
"qty": 1,
"unitPrice": 99,
"expectedShipTimestamp": 1412893800000,
"expectedDeliveryTimestamp": 1413325800000
}
],
"taxes": [
{
"type": "Sales Tax",
"amount": 10.06
}
],
"fees": [
{
"type": "CA E-Waste Fee",
"amount": 3
}
],
"totals": {
"subTotal": 114.96,
"shippingTotal": 0,
"taxTotal": 10.06,
"feesTotal": 3,
"grandTotal": 128.02
},
"shippingInfo": {
"fulfillmentType": "SHIPPING",
"fulfillmentOption": "S2H",
"shipMethod": "VALUE",
"address": {
"firstName": "Jane",
"lastName": "Doe",
"street1": "750 N Shoreline Blvd Apt 2",
"city": "Mountain View",
"stateOrProvinceCode": "CA",
"zip": "94043",
"extendedZip": "3212",
"countryCode": "USA",
"phone": "6502150456",
"modified": true,
"valid" : true
}
}
}
|
Address Validation
The "shippingInfo" field in the prepare request optionally takes an parameter "addressValidationMode" which is used to control the behaviour of address validation failure. The "address" field in response in turn has two fields, "modified" which indicates if the address was modified by Walmart and "valid" which indicates if address is valid. The behaviour of these two fields is summarized below,
| STRICT | LENIENT | |
| Valid Address |
valid : true modified: false |
valid : true modified: false |
| Valid Address with small correction (eg. zip) |
valid : true modified : true |
valid : true modifed : true |
| Invalid Address |
Error response with status code 40019 |
valid : false |
Passing an "Invalid Address" in STRICT mode returns an error response with status code 40019 whereas in LENIENT mode "valid" is set to false with a successful 200 response. Though our address validation service makes the best effort to validate an address, there are cases where valid addresses are called out as invalid. The consumer should treat our valid flag as a warning that the address could be probably wrong and allow for the customer to either make corrections or submit the address as is if the customer confirms.
Use the token received above in the Place Order call.
Place Order
Request:
curl -H "Authorization: Bearer dr9r4uue4a4mewejyyhm5x8q" -H "X-Walmart-User-IP: 127.0.0.1" -H "X-Walmart-User-Device-Type: browser" -H "X-Walmart-User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36" -d @place.json https://api.walmartlabs.com/v2/qa/order/place
place.json
{
"token": "31ce17ae-a9fe-4f60-aa08-8fac2bf4dd9d",
"paymentInfo": {
"cardInfo": {
"type": "VISA",
"cardNumber": "cjln+msVIlSJTmNN9i3gqMlwWV0diWNySMjSgSzetK3LTp80/IYNPF21wjgBBjaPtNnIzhrHcx+G/kejkN20MVYrrKG5goe6uoiSuPl/RbMv1OKon/b5Y+PKWB1HY9xiwLD1haDH939mi0lxbfpnDgULQR6MoaqRjn7hvaZIDjpb80R6aGP6Q4IpfmVcLvhfrBPmzc4tt2Zywx1CT3TxcuHZrujD5rl8L1vrCiqZFMvV9Z/h/r07HSHCsU/x+qUZDEb5B73qm68yZ9bS2dcJGw7l7grK+PFfRc66uSYcneWRHKWs8uhw9XiVuJXmxTUT5dbvHD8MZBVMS8XRPfeVUw==",
"expiryMonth": "04",
"expiryYear": "2016",
"firstName": "John",
"lastName": "Doe"
},
"email": "janedoe@gmail.com",
"phone": "6502150456",
"billingAddress": {
"street1": "850 Cherry Ave",
"city": "San Bruno",
"stateOrProvinceCode": "CA",
"zip": "94066",
"countryCode": "USA"
}
}
}
|
Response:
{
"orderId": "5091400341459"
}
|
CVV:
API does NOT expect CVV.
CVV should NOT be passed in the payload as plain text.
Work is in progress to to enhance API to accept encrypted CVV. Until otherwise communicated, CVV should not be part of payload.
Credit Card:
Card number to use for testing : 4012000077777777
Item id to use for testing : 173053133, 915607725, 256177555, 460509746, 578022998, 705958404, 21693006, 587663685, 460662331, 990814107, 270614402, 412257742, 627158116, 812376752
Note: some items can return out of stock
The "cardNumber" field in the above request is encrypted with JWT format string of the actual card number.
The exchange of credit card number is done using JWE (JSON Web Encryption). This is standard format for encrypting json based structures over web, as defined in RFC https://tools.ietf.org/html/rfc7516. There are a number of libraries opensource and propietary available implementing this standard, in all programming languages so it is easier to create a JWE encrypted JSON and decrypting.
We will be using JWE compact serialization for encrypting information.
Refer JWT: https://en.wikipedia.org/wiki/JSON_Web_Token
JWT Introduction: https://jwt.io/introduction/
Creating a JWE can be referred here https://connect2id.com/products/nimbus-jose-jwt/examples/jwt-with-rsa-encryption
A public documentation how JWE is created can be refered here https://medium.facilelogin.com/jwt-jws-and-jwe-for-not-so-dummies-b63310d201a3
JWT Libraries: https://jwt.io/
QA: Use the sample java code below which contains public key cert (X509 Certificate) used for encrypting credit card number.
Production: Please contact affilops@wal-mart.com for the public key cert (X509 Certificate) that you need to use for the encryption in production.
Example code to encrypt credit card and creating JWT format using the public key cert (in Java).
Note: For single digit months encrypt with one digit (do not pad with leading zero) i.e. January should be encrypted as 1 not as 01.
|
Order Status
Request:
GET https://api.walmartlabs.com/v2/qa/orders/{orderId}
|
Sample Request:
curl -X GET -H "Authorization: Bearer 6rvfc72fr3kg8j25sdakdy2e" -H "X-Walmart-User-IP: 127.0.0.1" -H "X-Walmart-User-Device-Type: browser" -H "X-Walmart-User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36" https://api.walmartlabs.com/v2/qa/orders/5091400341459 |
Sample Response:
{
"orderId" : "5091400341459",
"items" : [{
"itemId" : 21152035,
"itemTitle" : "Flexrake CLA105 Classic Flower & Vegetable Tiller",
"quantity" : 1,
"status" : "Shipped",
"itemPrice" : 11.98,
"trackingDetail" : {
"trackingUrl" : "http://wwwapps.ups.com/tracking/tracking.cgi?tracknum=1Z9400010383381123",
"trackingId" : "1Z9400010383381123",
"shippingService" : "UPS"
}
},{
"itemId" : 22906004,
"itemTitle" : "Suncast 20 cu ft Storage Shed, Taupe",
"quantity" : 1,
"status" : "Shipped",
"itemPrice" : 140.17,
"trackingDetail" : {
"trackingUrl" : "http://www.fedex.com/Tracking?action=track&language=english&cntry_code=us&initial=x&tracknumbers=808947542861234",
"trackingId" : "808947542861234",
"shippingService":"FedEx"
}
},{
"itemId" : 10295559,
"itemTitle" : "TRESemme Heat Tamer Spray, 8 fl oz",
"quantity" : 1,
"status" : "Processing",
"itemPrice" : 3.98
}],
"total" : 168.99,
"itemTotal" : 156.13,
"shipping" : 0,
"tax" : 12.86
}
|
Error Handling
Errors returned by the system will be of the form of
{
"errors": [
{
"code": 40005,
"message": "One or more of the items are invalid"
}
]
}
|
We will also return this response with proper HTTP Response code. For eg. in the above case the HTTP response code will be 400.
| HTTP Code | Error Code | Reason |
|---|---|---|
| 400 | 40001 | Invalid JSON |
| 400 | 40002 | Invalid token |
| 400 | 40003 | Order has already been placed |
| 400 | 40004 | Invalid order id |
| 400 | 40005 | One or more of the items are invalid |
| 400 | 40006 | One or more of the items are not available |
| 400 | 40007 | Card Number is invalid |
| 400 | 40008 | Card type is invalid |
| 400 | 40010 | Header missing |
| 400 | 40013 | Token expired. Please prepare a new order. |
| 400 | 40014 | customerInfo.email is not valid |
| 400 | 40015 | customerInfo.name is not valid |
| 400 | 40016 | customerInfo.phone is not valid |
| 400 | 40017 | qty is not valid |
| 400 | 40018 | shippingInfo.name is not valid |
| 400 | 40019 | shippingInfo.address is not valid |
| 400 | 40020 | shippingInfo.address.phone is not valid |
| 400 | 40021 | cardInfo.expiryMonth is not valid |
| 400 | 40022 | cardInfo.expiryYear is not valid |
| 400 | 40023 | Card has expired |
| 400 | 40024 | cardInfo.firstName or cardInfo.lastName is not valid |
| 400 | 40025 | paymentInfo.email is not valid |
| 400 | 40026 | paymentInfo.phone is not valid |
| 400 | 40027 | billingAddress is not valid |
| 400 | 40028 | One or more items in your request have gone out of stock |
| 400 | 40029 | cardNumber is not encrypted correctly |
| 400 | 40030 | Requested quantity not available for one or more items |
| 400 | 40031 | cardInfo.cvv should not be part of payload (do NOT pass cvv as part of json payload) |
| 400 | 40032 | The selected fulfillment option is not available for your location |
| 400 | 40033 | Not enough funds or limit exceeded |
| 500 | 50001 | Internal Server Error |
| 500 | 50002 | Card auth failed. This might be due to invalid card details. |
Developing with the QA environment
Once you begin development, you should first try out against our QA environment. This way you'd be able to iron out all issues and place successful mock orders without getting your credit card charged. The list of items and the corresponding seller ids which work in the QA environment is available here. Note that not all items in this list are guaranteed to work all the time and the list is subject to change.
You should use the following endpoints:
https://api.walmartlabs.com/v2/qa/oauth2/token
https://api.walmartlabs.com/v2/qa/order/prepare
https://api.walmartlabs.com/v2/qa/order/place
https://api.walmartlabs.com/v2/qa/orders/{orderId}
Production environment
When you are ready to move to production environment you can change your endpoints to:
https://api.walmartlabs.com/v2/oauth2/token
https://api.walmartlabs.com/affiliates/checkout/prepare-order
https://api.walmartlabs.com/affiliates/checkout/place-order
https://api.walmartlabs.com/affiliates/checkout/order-status/{orderId} - Previous: JSONP Response
- Up: Product Lookup API
- Next: