PX SubmitOrder
PX SubmitOrder API product provides CenturyLink partners ability to retrieve RCC text that can be read to a customer or sent electronically and upon acceptance they can complete the order
This describes the Partner API specifications for partners wishing to configure CenturyLink available products, services and purchase on behalf of their customers. The new Px system enables partners to seamlessly and securely transact with CenturyLink electronically on cloud based next generation CRM platforms. The products supported as part of the current version of Partner APIs include Local Service packages, Long Distance packages, Broadband internet access and product bundles containing two or more products. The APIs also offer the ability to configure modems, services (e.g. broadband installation services), and accessories (for example CenturyLink @Ease).
SubmitOrder API includes:
· Retrieve RCC service
· Send RCC service
. Get RCC Acceptance service
. Complete Order service
Mass Market Partner APIs are available to new and existing partners who are selling local service packages, long-distance packages, broadband internet access, and product bundles to CenturyLink consumers and small business customers.
Mass Markets Partner APIs enable partners to seamlessly and securely qualify products and place orders with CenturyLink electronically on cloud-based next-generation CRM platforms. Digital information sharing between CenturyLink and our partners increases the speed and accuracy of products and services being delivered to the end customer.
1. Register a user.
2. Create sandbox and production apps under My Apps.
2. Obtain API keys. Upon approval, sandbox and production credentials will move to approved status. If you have questions about approvals use the Contact Us form.
3. Setup authorization. Using the navigation menu go to Code Samples for sample code for setting up authorization.
4. Make your first call. Using the navigation menu go to Documentation/Specification.
a. Click on the authorize button and add your credentials.
b. Select the POST/pxRetrieveRCC API.
c. Click on the “Try it out” button.
d. Fill in the parameters and customize the sample code.
e. Click the execute button to see the response.
The below diagram depicts high level process flow for all partner APIs
Partner will send the following details in the Get RCC API request.
- Partner authorization details
Px will then the return the appropriate RCC text to be formatted for the partner agent to read out to the customer.
Send RCC
Partners will call this service if customer requests RCC’s to be sent electronically. This will trigger RCC’s to be sent via SMS or Email (rather than delivering verbally). This will trigger RCC to be sent to the customer in method selected.
Get RCC Acceptance
Partners would call this service if they triggered RCC’s to be sent via SMS or Email (rather than delivering verbally). This will retrieve method of acceptance by the customer. Only after acceptance has been confirmed by the customer should this call be made (so that the acceptance confirmation and method will be retrieved). Px will store confirmation of RCC acceptance via method delivered (i.e. verbal, email, or sms).
Complete Order
Partner will send the following details in the Complete API request
- Partner authorization details
- RCC Accepted
Px will then send the order details in the response.
When setting up your Apps in My Apps you can create a Sandbox app and a Production app. You will then have two different sets of Consumer Keys and Consumer Secrets.
Base URL Sandbox: https://api-test.lumen.com/
Base URL Prod: https://api.lumen.com/
The Sandbox (test) environment is available to developers to build initial code against. It is a snapshot of production type data so that you can try out requests and responses. The Sandbox is not meant to be used as a QA environment. It is also not meant to duplicate production, therefore data that exists in Production may not be present in the Sandbox environment. Sandbox does not represent the up-time expectations of Production. We recommend that you complete shakeout testing against Production, keeping in mind that all transactions will be live.
Lumen supports the OAuth 2.0 client credentials authorization grant flow for external access by client-side applications. Once your credentials are approved you can go to Using OAuth 2.0 for detailed steps on getting a bearer token using basic authorization base64 encoding. Use the navigation menu and select Code Samples for an example of authorization.
PxAuthenticationService.java
----------------------------
package com.ctl.px.api.client;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
import org.apache.oltu.oauth2.client.OAuthClient;
import org.apache.oltu.oauth2.client.URLConnectionClient;
import org.apache.oltu.oauth2.client.request.OAuthClientRequest;
import org.apache.oltu.oauth2.client.response.OAuthJSONAccessTokenResponse;
import org.apache.oltu.oauth2.common.OAuth;
import org.apache.oltu.oauth2.common.message.types.GrantType;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
@Service
public class PxAuthenticationService {
Logger log = LoggerFactory.getLogger(PxAuthenticationService.class);
@Value("${px.sf.token.url}")
private String tokenURL;
@Value("${px.sf.token.basicAuth}")
private String basicAuth;
public String getAccessToken() {
String accessToken = null;
String methodName = new Object() {
}.getClass().getEnclosingMethod().getName();
try {
OAuthClient client = new OAuthClient(new URLConnectionClient());
OAuthClientRequest request = OAuthClientRequest.tokenLocation(tokenURL)
.setGrantType(GrantType.CLIENT_CREDENTIALS).buildBodyMessage();
request.addHeader(OAuth.HeaderType.AUTHORIZATION, "Basic " + basicAuth);
accessToken = client.accessToken(request, OAuthJSONAccessTokenResponse.class).getAccessToken();
} catch (Exception exn) {
exn.printStackTrace();
}
return accessToken;
}
}
PxRetrieveRccClient.java
------------------------
package com.ctl.px.api.client;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;
import com.ctl.px.api.model.RetrieveRccRequestObj;
@Component
public class PxRetrieveRccClient {
@Autowired
private PxAuthenticationService authenticationService;
@Autowired
private RestTemplateBuilder restTemplateBuilder;
@Value("${px.retrieveRCC.url}")
private String retrieveRCCurl;
Logger log = LoggerFactory.getLogger(PxRetrieveRccClient.class);
public ResponseEntity<String> retrieveRcc(RetrieveRccRequestObj retrieveRccRequest) {
RestTemplate restTemplate;
restTemplate = restTemplateBuilder.build();
String accessToken = authenticationService.getAccessToken();
log.debug("Using access token: " + accessToken);
HttpHeaders headers = new HttpHeaders();
headers.add("Authorization", "Bearer " + accessToken);
headers.setContentType(MediaType.APPLICATION_JSON);
restTemplate.getMessageConverters().add(new MappingJackson2HttpMessageConverter());
ResponseEntity<String> response = null;
try {
HttpEntity<RetrieveRccRequestObj> request = new HttpEntity<>(retrieveRccRequest, headers);
response = restTemplate.postForEntity(retrieveRCCurl, request, String.class);
} catch (Exception e) {
log.debug("Exception occurred while making rest call to " + retrieveRCCurl + ", Exception was: "
+ e.getStackTrace());
}
return response;
}
}
PxSendRccClient.java
--------------------
package com.ctl.px.api.client;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;
import com.ctl.px.api.model.SendRccApiRequest;
@Component
public class PxSendRccClient {
@Autowired
private PxAuthenticationService authenticationService;
@Value("${px.sendRcc.url}")
private String sendRccUrl;
@Autowired
private RestTemplateBuilder restTemplateBuilder;
Logger log = LoggerFactory.getLogger(PxSendRccClient.class);
public ResponseEntity<String> sendRcc(SendRccApiRequest sendRccApiRequest) {
RestTemplate restTemplate;
restTemplate = restTemplateBuilder.build();
String accessToken = authenticationService.getAccessToken();
log.debug("Using access token: " + accessToken);
HttpHeaders headers = new HttpHeaders();
headers.add("Authorization", "Bearer " + accessToken);
headers.setContentType(MediaType.APPLICATION_JSON);
restTemplate.getMessageConverters().add(new MappingJackson2HttpMessageConverter());
ResponseEntity<String> response = null;
try {
HttpEntity<SendRccApiRequest> request = new HttpEntity<>(sendRccApiRequest, headers);
response = restTemplate.postForEntity(sendRccUrl, request, String.class);
} catch (Exception e) {
log.debug("Exception occurred while making rest call to " + sendRccUrl + ", Exception was: "
+ e.getStackTrace());
}
return response;
}
}
PxGetRccAcceptanceClient.java
-----------------------------
package com.ctl.px.api.client;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;
import com.ctl.px.api.model.GetRCCAcceptanceApiRequest;
@Component
public class PxGetRccAcceptanceClient {
@Autowired
private PxAuthenticationService authenticationService;
@Value("${px.getRccAcceptance.url}")
private String getRccAcceptanceUrl;
@Autowired
private RestTemplateBuilder restTemplateBuilder;
Logger log = LoggerFactory.getLogger(PxGetRccAcceptanceClient.class);
public ResponseEntity<String> getRccAcceptance(GetRCCAcceptanceApiRequest getRCCAcceptanceRequest) {
RestTemplate restTemplate;
restTemplate = restTemplateBuilder.build();
String accessToken = authenticationService.getAccessToken();
log.debug("Using access token: " + accessToken);
HttpHeaders headers = new HttpHeaders();
headers.add("Authorization", "Bearer " + accessToken);
headers.setContentType(MediaType.APPLICATION_JSON);
restTemplate.getMessageConverters().add(new MappingJackson2HttpMessageConverter());
ResponseEntity<String> response = null;
try {
HttpEntity<GetRCCAcceptanceApiRequest> request = new HttpEntity<>(getRCCAcceptanceRequest, headers);
response = restTemplate.postForEntity(getRccAcceptanceUrl, request, String.class);
} catch (Exception e) {
log.debug("Exception occurred while making rest call to " + getRccAcceptanceUrl + ", Exception was: "
+ e.getStackTrace());
}
return response;
}
}
PxCompleteOrderClient.java
--------------------------
package com.ctl.px.api.client;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;
import com.ctl.px.api.model.CompleteRequestObj;
@Component
public class PxCompleteOrderClient {
@Autowired
private PxAuthenticationService authenticationService;
@Autowired
private RestTemplateBuilder restTemplateBuilder;
@Value("${px.completeOrder.url}")
private String completeOrderUrl;
Logger log = LoggerFactory.getLogger(PxCompleteOrderClient.class);
public ResponseEntity<String> completeOrder(CompleteRequestObj completeOrderRequest) {
RestTemplate restTemplate;
restTemplate = restTemplateBuilder.build();
String accessToken = authenticationService.getAccessToken();
log.debug("Using access token: " + accessToken);
HttpHeaders headers = new HttpHeaders();
headers.add("Authorization", "Bearer " + accessToken);
headers.setContentType(MediaType.APPLICATION_JSON);
restTemplate.getMessageConverters().add(new MappingJackson2HttpMessageConverter());
ResponseEntity<String> response = null;
try {
HttpEntity<CompleteRequestObj> request = new HttpEntity<>(completeOrderRequest, headers);
response = restTemplate.postForEntity(completeOrderUrl, request, String.class);
} catch (Exception e) {
log.debug("Exception occurred while making rest call to " + completeOrderUrl + ", Exception was: "
+ e.getStackTrace());
}
return response;
}
}
API Name | Reason | API Status Code | Internal Message Code | User Message |
Get RCC | Sales code | 401 | 2000 | Missing or Invalid <B>; TxID <> |
Get RCC | Partner ID | 401 | 2030 | Missing or Invalid <B>; TxID <> |
Get RCC | addressDetailId | 401 | 2025 | Missing or Invalid <B>; TxID <> |
Get RCC | Transaction Id | 410 | 2070 | Missing or Invalid <B>; TxID <> |
Get RCC | Partner Order ID is not provided | 2225 | Missing Partner Order Id <>; TxID <> | |
Get RCC | Partner Order ID and transaction combination must be unique to a config request and must remain constant thru order submit. Cannot submit a new Partner Order ID with an already used transaction ID on a new config request. Cannot alter partner order ID and transaction ID through the order flow through submit request. |
410 | 2131 | Transaction Id <B> and PartnerOrderId <> combination must remain constant through Submit; TxID <> |
Get RCC | taxEstimate service not available | 500 | 4040 | Centurylink taxEstimateService unavailable; TxID <> |
Get RCC | No RCC is returned should raise error and block Complete API (RCC is required to proceed). | 500 | 4050 | Downstream applications failed, cannot process order at this time. Please contact Centurylink 1-800-xxx xxxx (from sales code) to process your order? TxID <> |
Complete | RCC requested and accepted? | 401 | 1210 | RCC must be accepted to submit an order, please correct and resubmit; TxID <> |
Complete | Sales code | 401 | 2000 | Missing or Invalid <B>; TxID <> |
Complete | Partner ID | 401 | 2030 | Missing or Invalid <B>; TxID <> |
Complete | addressDetailId | 401 | 2025 | Missing or Invalid <B>; TxID <> |
Complete | Payment declined - Card was declined by paymet system | 410 | 1099 | Invalid credit card information. Authorization Failed Please correct and resend TxID <> |
Complete | Payment service down | 401 | Payment system is down please contact CenturyLink at <B>; TxID <> | |
Complete | If payment required but PaymentToken not provided | 410 | 1130 | Because payment is required, token must be provided. Please correct and resend. TxID <> |
Complete | Partner Order ID is not provided (but is required)? | 2225 | Missing Partner Order Id <>; TxID <> | |
Complete | Already received and processed submitted order (cannot change a submitted order or submit again) | 410 | 2130 | Order shows already submitted and may not be submitted again; TxID <> |
Complete | Can only select one gift card (cannot select more then 1 giftcard) | 410 | 1215 | Only one gift card can be submitted, please correct and resubmit; TxID <> |
Complete | A complete connot be submitted >120 minutes after succesful prepare |
410 | 2215 | A complete order cannot be executed more than 120 minutes after the corresponding prepare Order TxID <> |
Complete | Partner Order ID and transaction combination must be unique to a config request and must remain constant thru order submit. Cannot submit a new Partner Order ID with an already used transaction ID on a new config request. Cannot alter partner order ID and transaction ID through the order flow through submit request. |
410 | 2131 | Transaction Id <B> and PartnerOrderId <> combination must remain constant through Submit; TxID <> |
Partners who would like to have API access please contact PXAPIAccessandSupport@lumen.com.
For API-specific support please complete the support form select the Help -> Contact Us menu option.