Authentication

To authenticate an API call successfully, pass a Consumer ID and digital signature in the header for every API call.

Register as a Walmart Drop Ship Vendor to receive a Consumer ID and Private Key. Log into the Developer Portal to obtain these items. For instructions, See Introduction to DSV APIs.

You can use the Consumer ID and Private Key, along with other required header parameters, to generate a digital signature.

Integration Process

You can integrate with the DSV APIs by calling an API and generating a digital signature. 

1. Choose a simple GET method to call one of the DSV resources.  For example, call GET Feed Status: GET /v3/feedstatus.
2. Generate a digital signature.
   Note: The digital signature will expire in 15 minutes; regenerate the signature using the same procedure. There are two ways to generate a digital signature: 
   • Generate a Digital Signature using an executable JAR file (Recommended)
   • Generate a Digital Signature with self-written code

Using the executable JAR file will eliminate a majority of authentication issues.

Pass the following header keys to authenticate your API call:

Name	Description	Required	Example
WM_SVC.NAME	Walmart Service Name	Yes	Walmart Gateway API
WM_QOS.CORRELATION_ID	A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID	Yes	1234hfvgtr
WM_SEC.TIMESTAMP	The Epoch timestamp	Yes	1443748249449
WM_SEC.AUTH_SIGNATURE	The vendor’s digital signature, generated by running the JAR file or custom generation code	Yes	9fg3TPeRt0WSGbXNGGj4kSQ9L6PMBX/q+ovdy9bDQfvdhYs8NoEsjRX4fD7UNIHTddgkmSVqAqeIIHlaLcRIl0Y4DcJqQYHL27LiWlsm91nYodGssWTKsOq6dJfUHEy95M4zXFGWDDhbHYCor28SCV/g/JdEQybGkcX9Zj5aDyg=
WM_CONSUMER.CHANNEL.TYPE	A unique ID to track the consumer request by channel	Yes	0f3e4dd4-0514-4346-b39d-… use the Consumer Channel Type received during onboarding
WM_CONSUMER.ID	A unique ID required to access the API	Yes	Get the Consumer ID from Developer Center after logging in
Accept	The returned data format in the response	No	application/xml

Note: Content Type for Get calls is not required but may be automatically pre-filled and cause a system error during authentication. If you receive this error, check to see if Content Type is included as a header parameter and remove it.

If you are having trouble connecting to Developer Center, refer to Troubleshooting.

1. Make sure the call does not throw a 400 or 401 error. For more information, refer to Error Codes.
   • If a 400 HTTP status code is received, validate the mandatory headers and all mandatory query or path parameters.
   • If a 401 HTTP status code is received, verify the digital signature.

Generate a Digital Signature Using an Executable JAR File (Recommended):

To generate a digital signature using the executable JAR file, follow these steps:

1. Download Java 6.0 or greater. If it is not installed on your computer, go to: https://java.com/en/download
2. Download the executable JAR file: digitalSignatureUtil-1.0.0.jar
   
   
3. Use the following command to run the executable JAR file: java -jar DigitalSignatureUtil-1.0.0.jar DigitalSignatureUtil {requestUrl} {consumerId} {privateKey} {requestMethod} {filePath}

Note: Your program must run this executable JAR file in the directory where the executable JAR file is located.

Running the executable JAR file returns the following two headers as the console output:

• WM_SEC.AUTH_SIGNATURE
• WM_SEC.TIMESTAMP

The executable JAR file uses five parameters; see the table below:

Name	Description	Required
requestUrl	The full URL to call, including path and query parameters	Yes
consumerId	The Consumer ID retrieved from Developer Center after login	Yes
privateKey	The vendor’s Base-64-encoded, PKCS#8 stored Private Key	Yes
requestMethod	Use method GET (all capital letters) to call this API	Yes
filePath	The absolute (full) path of the file desired for the digital signature and timestamp. The digital signature and timestamp can also be viewed in the console.	Yes

Note: Generate a digital signature and timestamp for every API call, even if it is for the same API. Sample call to the executable JAR

---

java -jar DigitalSignatureUtil-1.0.0.jar DigitalSignatureUtil https://api-gateway.walmart.com/v3/feeds/d4885da4-9bc1-4296-b26f-57e3cb0e0fc9?includeDetails=true 9a4d7659-100c-4d5e-a6b0-26faad4c9132 MIICeAIBADANBgkqhkiG9w0BAQEFAA... GET HelloWorld

Sample output authentication signature (Note For security reasons, the authentication signature is truncated.)

---

WM_SEC.AUTH_SIGNATURE:Lhq8pXEC9...
WM_SEC.TIMESTAMP:1438149671421

Generate a Digital Signature with self-written code

To get the digital signature using self-written code, follow these steps:

1. Get the Consumer ID and Private Key from the Developer Portal.
2. Get the full URL you wish to call, including any path and query parameters.
3. Use the GET method to construct an input for the digital signature.

Use the structure listed below:

The Consumer ID_ + “\n” + the URL of the API call + “\n” + the request method of the API call in all capitals + “\n” + the current Unix epoch timestamp + “\n”

Note: The order of the parameters and the line returns \n are important to generate the signature properly; see the sample code in the right pane.

1. Generate the byte array of the structured data listed in step 3 using the following steps:
   1. Decode the byte array with Base-64.
   2. Encode the resulting value using PKCS#8 to represent your Private Key.
      Libraries in various languages offer the ability to identify that the Private Key is in PKCS#8 format and not in other conflicting formats such as PKCS#1.
   3. Use this byte representation of the Private Key to sign the data using SHA-256 with RSA.
   4. Encode the generated digital signature using Base 64.
2. Use the generated digital signature and Unix epoch timestamp to make an API call.

Sample Signing Code: JAVA

import org.apache.commons.codec.binary.Base64;
import java.security.KeyFactory;
import java.security.PrivateKey;
import java.security.Signature;
import java.security.spec.PKCS8EncodedKeySpec;

public class SHA256WithRSAAlgo {
  private static String consumerId = "b68d2a72...."; // Trimmed for security reason
  private static String baseUrl = "https://api-gateway.walmart.com/v3/feeds";
  private static String privateEncodedStr = "MIICeAIBADANBgkqhkiG9w0BAQEFAA......";       //Trimmed for security reasons
  public static void main(String[] args) {
    String httpMethod = "GET";
    String timestamp = String.valueOf(System.currentTimeMillis());
    String stringToSign = consumerId + "\n" + baseUrl + "\n" + httpMethod + "\n" + timestamp + "\n";
    String signedString = SHA256WithRSAAlgo.signData(stringToSign, privateEncodedStr);
    System.out.println("Signed String: " + signedString);
  }
  public static String signData(String stringToBeSigned, String encodedPrivateKey) {
    String signatureString = null;
    try {
      byte[] encodedKeyBytes = Base64.decodeBase64(encodedPrivateKey);
      PKCS8EncodedKeySpec privSpec = new PKCS8EncodedKeySpec(encodedKeyBytes);
      KeyFactory kf = KeyFactory.getInstance("RSA");
      PrivateKey myPrivateKey = kf.generatePrivate(privSpec);
      Signature signature = Signature.getInstance("SHA256withRSA");
      signature.initSign(myPrivateKey);
      byte[] data = stringToBeSigned.getBytes("UTF-8");
      signature.update(data);
      byte[] signedBytes = signature.sign();
      signatureString = Base64.encodeBase64String(signedBytes);
    } catch (Exception e) {
      e.printStackTrace();
    }
    return signatureString;
  }
}

Troubleshooting

New users can experience difficulty when trying to integrate with the platform for the first time. Typically, errors occur when incorrect headers are generated (such as the timestamp or authentication signature). To avoid errors, use the headers listed in the header samples displayed in each corresponding section. Sample Request Header

---

WM_SVC.NAME: Drop Ship Vendor Services
WM_CONSUMER.ID: a20ac266-9add-4fc7-9392-fec303f5155c
WM_SEC.TIMESTAMP: 1438147839
WM_SEC.AUTH_SIGNATURE: j7Lh5PeRt0WSGbXNGGj4kSQ9L6PMBX/q+ovdy9bDQfvdhYs8NoEsjRX4fD7UNIHTddgkmSVqAqeIIHlaLcRIl0Y4DcJqQYHL27LiWlsm91nYodGssWTKsOq6dJfUHEy95M4zXFGWDDhbHYCor28SCV/g/JdEQybGkcX9Zj5aDyg=
WM_CONSUMER.CHANNEL.TYPE: 0f3e4dd4-0514

Testing the API Calls

To accelerate development, you can use an online tool such as the Google Chrome Advanced Rest Client App (ARCA), Postman, etc.

To test your API calls using the ARCA, follow the steps below:

1. Enter the URL: https://api-gateway.walmart.com/v3/feeds?feedType=SUPPLIER_FULL_ITEM
2. Select GET from the drop-down menu.
3. Configure the headers as listed in step 3 of the ‘Integration Steps’ section.
4. Click Send.

If basic API calls are successful from the ARCA but are not successful from the self-written code, the problem lies in the self-written code. If the calls fail from the ARCA, there is a problem with the headers in the call.

Troubleshooting Hints

• If the call from the ARCA succeeds, the headers are correct. However, if the call fails, examine the headers.
• If the call from the ARCA fails and you are not using the executable JAR file, generate the headers using the executable JAR file and try again. If the call now succeeds, either start using the executable JAR file in place of the self-written authentication code, or adjust the self-written code to generate the headers correctly.
• If the call from the ARCA fails while using the executable JAR file, generate a new set of credentials from Developer Portal and retry with the new credentials. This ensures that the credentials are not obsolete, or you have not reset the Private Key recently.
• If the ARCA is configured correctly and the most current credentials are being used, but errors still exist, contact Partner Support.