PX SubmitOrder

API Overview

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.

Getting started

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.

Authentication / Authorization

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.

Documentation / Specification

Code Samples

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;

@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;

@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 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;

}

Status and Error Codes

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 <>

Support

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.