OTT Integration: API Version 1.0 Use Cases

Contents

• Overview
• Uses Cases
  • POST /account/validate Use Cases
  • POST /pin Use Cases
  • POST /transaction Use Cases
  • GET /transaction Use Cases
  • POST /notification Use Cases
• Revision History

Overview

This topic contains MarketONE API Version 1.0 use cases that are required for over-the-top (OTT) provider onboarding with MarketONE, and then for integrating with a communications service provider (CSP).

Note: These use cases are used for the certification of an OTT that onboards with MarketONE, with or without a corresponding CSP.

Uses Cases

POST /account/validate Use Cases

1. Validate the Account by the Account Identifier (Active)

• Category: Account
• Sub-Category: Account validation
• Data Requirement: The account is active.
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /account/validate 

  Response:
  

  HTTP 200 - OK
  {
     "status": "ACTIVE",
     "type": "postpaid"
  }

• Expected OTT Behaviour: The OTT continues to the next API in the purchase flow.

2. Validate the Account by the Account Identifier (Inactive)

• Category: Account
• Sub-Category: Account validation
• Data Requirement: The account is inactive (it is ceased or it does not exist).
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /account/validate 

  Response:
  

  HTTP 404 - Not found
  {
     "code": "account-not-found",
     "message": "Account not found"
  }

• Expected OTT Behaviour: The OTT cannot continue to other APIs due to purchase flow failure.

3. Validate the Account by the Account Identifier (Suspended - No Payment)

• Category: Account
• Sub-Category: Account validation
• Data Requirement: The account is suspended (for non-payment).
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /account/validate 

  Response:
  

  HTTP 400 - Bad request
  {
     "code": "suspended-non-payment",
     "message": "Account is suspended because of non-payment, or other billing issue"
  }

• Expected OTT Behaviour: The OTT cannot continue to other APIs due to purchase flow failure.

4. Validate the Account by the Account Identifier (Suspended - Lost or Stolen)

• Category: Account
• Sub-Category: Account validation
• Data Requirement: The account is suspended (phone is either lost or stolen).
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /account/validate 

  Response:
  

  HTTP 400 - Bad request
  {
     "code": "suspended-lost-stolen",
     "message": "Account is suspended because of lost phone"
  }

• Expected OTT Behaviour: The OTT cannot continue to other APIs due to purchase flow failure.

5. Validate the Account by the Account Identifier (Fails - Eligibility Check)

• Category: Account
• Sub-Category: Account validation
• Data Requirement: The account is active, but the request fails (is not valid) against an additional eligibility check.
  Note: This is a CSP-specific condition (depending upon which CSP the OTT is integrated with).
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /account/validate 

  Response:
  

  HTTP 400 - Bad request
  {
     "code": "eligibility-failed csp",
     "message": "You are not eligible to subscribe to this service based on rules set by your CSP"
  }

• Expected OTT Behaviour: The OTT cannot continue to other APIs due to purchase flow failure.

6. Validate Account by the Account Identifier (Account not Found)

• Category: Account
• Sub-Category: Account validation
• Data Requirement: The account identifier does not exist in the CSP's billing system (either wrong number, or wrong length, or wrong format).
  
• API Request and Expected Response from M1 (Validation Criteria):
  
  Request:
  

  POST /account/validate 

  Response:
  

  HTTP 404 - Not found
  {
     "code": "account-not-found",
     "message": "Account not found"
  }

• Expected OTT Behaviour: The OTT cannot continue to other APIs due to purchase flow failure.

7. Mandatory Field Check (Invalid Format)

• Category: Account
• Sub-Category: Account validation
• Data Requirement: The request is invalid due to an invalid format (for example: "abc").
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /account/validate
  {
     "type": "MSISDN",
     "address": "abc"
  } 

  Response:
  

  HTTP 400 - Bad request
  {  
     "code":"invalid-request",
     "message":"Invalid request.",
     "validationErrors":[      {
           "code":"violation-on-address",
           "reason":"must match \"^[0-9]{10}$\""
        }
     ]
  }

• Expected OTT Behaviour: The OTT cannot continue to other APIs due to purchase flow failure.

POST /pin Use Cases

8. Request MarketONE to Generate a PIN for the Verification of the Account Owner (Valid MSISDN)

• Category: PIN
• Sub-Category: PIN generation
• Data Requirement: A valid MSISDN is sent with the request.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /pin 

  Response:
  

  HTTP 201 - Created
  

  Note: The PIN is sent via SMS.

• Expected OTT Behaviour: The OTT continues to the next API in the purchase flow.

9. Request MarketONE to Generate a PIN for the Verification of the Account Owner (Nonexistent MSISDN)

• Category: PIN
• Sub-Category: PIN generation
• Data Requirement: The MSISDN that is used does not exist in the test data pool.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /pin 

  Response:
  

  HTTP 404 - Not found
  {
     "code":"account-not-found",
     "message":"Account not found"
  }		

• Expected OTT Behaviour: The OTT cannot continue to other APIs due to purchase flow failure.

10. Validate the PIN from PIN Generation (Success)

• Category: PIN
• Sub-Category: PIN validation
• Data Requirement: The same PIN from the PIN generation step is entered.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /pin/validation 

  Response:
  

  HTTP 201 - Created		

• Expected OTT Behaviour: The OTT continues to the POST /transaction API.

11. Validate the PIN from PIN Generation (Fail)

• Category: PIN
• Sub-Category: PIN validation
• Data Requirement: A different PIN from the PIN generation step is entered.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /pin/validation 

  Response:
  

  HTTP  400 - Bad request
  {
     "code":"invalid-pin",
     "message":"Invalid pin"
  }		

• Expected OTT Behaviour: The OTT cannot continue to the POST /transaction API due to purchase flow failure.

12. Validate the PIN from PIN Generation (Timeout)

• Category: PIN
• Sub-Category: PIN validation
• Data Requirement: The same PIN from the PIN generation step is entered after the PIN is expired.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /pin/validation 

  Response:
  

  HTTP  400 - Bad request
  {
     "code":"invalid-pin",
     "message":"Invalid pin"
  }		

• Expected OTT Behaviour: The OTT cannot continue to the POST /transaction API due to purchase flow failure.

13. Validate the PIN from PIN Generation (Successful Retry)

• Category: PIN
• Sub-Category: PIN validation
• Data Requirement: A different PIN from the PIN generation step is entered, and then the same PIN from the PIN generation step is entered.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /pin/validation 

  Response:
  

  HTTP  201 - Created		

• Expected OTT Behaviour: The OTT continues to the POST /transaction API.

POST /transaction Use Cases

14. Post the Charge to the CSP's Bill (Success)

• Category: Charging
• Sub-Category: Transaction
• Data Requirement: The MSISDN is associated with a valid account and is eligible, and the request has all of the correct parameters.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /transaction 

  Response:
  

  HTTP 200 - OK
  {
     "extTransactionId":"15094524571",
     "status":"Success",
     "description":"Charge success"
  }		

• Expected OTT Behaviour: The purchase is successfully posted to the bill.

15. Post the Charge to the CSP's Bill Idempotently (Success)

• Category: Charging
• Sub-Category: Transaction
• Data Requirement: The MSISDN is associated with a valid account and is eligible, and the same request is sent multiple times (idempotently).
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /transaction 

  Response:
  

  HTTP 200 - OK
  {
     "extTransactionId":"15094524571",
     "status":"Success",
     "description":"Charge success"
  }		

• Expected OTT Behaviour: There is no change to the customer's bill.

16. Post the Charge to the CSP's Bill (Incorrect Account ID - Fail)

• Category: Charging
• Sub-Category: Transaction
• Data Requirement: The MSISDN is associated with a valid account and is eligible, and the same request is sent with a non-existent MarketONE account ID.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /transaction 

  Response:
  

  HTTP 404 - Not found
  {
     "code":"account-not-found",
     "message":"Account not found"
  }		

• Expected OTT Behaviour: The purchase fails, and there is no change to the customer's bill.

17. Post the Charge to the CSP's Bill (Incorrect Currency)

• Category: Charging
• Sub-Category: Transaction
• Data Requirement: The MSISDN is associated with a valid account and is eligible, and the request has the incorrect currency.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /transaction 

  Response:
  

  HTTP 400 - Bad request
  {  
     "code":"invalid-request",
     "message":"Invalid request",
     "validationErrors":[      {
           "code":"violation-on-currency",
           "reason":"must match \"^[A-Z]{3}$\""
        }
     ]
  }		

• Expected OTT Behaviour: The purchase fails, and there is no change to the customer's bill.

18. Post the Charge to the CSP's Bill (Nonexistent Product ID)

• Category: Charging
• Sub-Category: Transaction
• Data Requirement: The MSISDN is associated with a valid account and is eligible, and the request contains a product ID that does not exist.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /transaction 

  Response:
  

  HTTP 400 - Bad request
  {
     "code":"invalid-partner-product",
     "message":"Product not defined"
  }		

• Expected OTT Behaviour: The purchase fails, and there is no change to the customer's bill.

19. Post the Refund to the CSP's Bill (Success)

• Category: Charging
• Sub-Category: Refund
• Data Requirement: The POST /transaction call is successful, and a negative amount is given to the same external transaction ID.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /transaction 

  Response:
  

  HTTP 200 - OK

  {
     "extTransactionId":"12345678",
     "status":"Success",
     "description":"Charge success"
  }		

• Expected OTT Behaviour: The refund is successfully posted.

20. Post the Refund to the CSP's Bill Idempotently (Success)

• Category: Charging
• Sub-Category: Refund
• Data Requirement: The POST /transaction call is successful, a negative amount is given to the same external transaction ID, and the same refund charge is sent multiple times (idempotently).
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /transaction 

  Response:
  

  HTTP 200 - OK

  {
     "extTransactionId":"12345678",
     "status":"Success",
     "description":"Charge success"
  }
  
  Note: "Charge success" is returned in the response, but MarketONE is not doing refunds twice with the CSP.		

• Expected OTT Behaviour: The refund fails, and there is no change to the customer's bill.

21. Post the Refund to the CSP's Bill (Fail)

• Category: Charging
• Sub-Category: Refund
• Data Requirement: The POST /transaction call is successful, and the external transaction ID provided does not match any of the existing transactions within MarketONE.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /transaction 

  Response:
  

  HTTP 404 - Not found
  {
     "code":"invalid-charge-refund",
     "message":"Original transaction not found"
  }		

• Expected OTT Behaviour: The refund fails, and there is no change to the customer's bill.

22. Post the Refund to the CSP's Bill (Fail)

• Category: Charging
• Sub-Category: Refund
• Data Requirement: The POST /transaction call is successful, and the enternal transaction ID is empty.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /transaction 

  Response:
  

  HTTP 400 - Bad request
  {   
     "code":"invalid-request",
     "message":"Invalid request.",
     "validationErrors":[      {
           "code":"reference-id-required",
           "reason":"Reference Id is required to proceed refund transaction"
        }
     ]
  }		

• Expected OTT Behaviour: The refund fails, and there is no change to the customer's bill.

23. Post the Refund to the CSP's Bill (Fail)

• Category: Charging
• Sub-Category: Refund
• Data Requirement: The POST /transaction call is successful, and the refund amount is a positive value.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /transaction 

  Response:
  

  HTTP 400 - Bad request
  {   
     "code":"invalid-request",
     "message":"Invalid request",
     "validationErrors":[      {
           "code":"negative-amount",
           "reason":"Negative Amount is required to proceed refund transaction"
        }
     ]
  }		

• Expected OTT Behaviour: The refund fails, and there is no change to the customer's bill.

GET /transaction Use Cases

24. Request MarketONE to Return the Order Status (Success)

• Category: Transaction Status Check
• Sub-Category: View Transaction
• Data Requirement: Call with extTransactionID exists in MarketONE.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  GET /transaction/{extTransactionID} 

  Response:
  

  HTTP 200 - OK
  {
     "chargeDate":"2020-05-18T15:05:03Z",
     "currency":"MXN",
     "amount":"1500.0",
     "message":"Over spending daily limit",
     "status":"Failure"
  }		   						

• Expected OTT Behaviour: The status check is successful.

25. Request MarketONE to Return the Order Status (Fail)

• Category: Transaction Status Check
• Sub-Category: View Transaction
• Data Requirement: Call with extTransactionID does not exist in MarketONE.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  GET /transaction/{extTransactionID} 

  Response:
  

  HTTP 404 - Not found
  {
     "code":"transaction-not-found",
     "message":"Transaction not found"
  }		   						

• Expected OTT Behaviour: The status check fails.

POST /notification Use Cases

26. Request MarketONE to Send a Notification (Success)

• Category: Notification
• Data Requirement: Call with the correct parameters and type.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /notification 

  Response:
  

  HTTP 201 - Created		   						

• Expected OTT Behaviour: The notification is successful, and the user receives the message.

27. Request MarketONE to Send a Notification (Fail)

• Category: Notification
• Data Requirement: Call with no message.
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /notification 

  Response:
  

  HTTP 400 - Bad request
  {   
     "code":"invalid-request",
     "message":"Invalid request.",
     "validationErrors":[      {
           "code":"violation-on-message",
           "reason":"must not be null"
        }
     ]
  } 						

• Expected OTT Behaviour: The notification fails, and the user does not receive the message.

28. Request MarketONE to Send a Notification (Fail)

• Category: Notification
• Data Requirement: Call with invalid type (SMS instead of MSISDN).
  
• API Request and Expected Response from M1 (Validation Criteria):
  Request:
  

  POST /notification 

  Response:
  

  HTTP 400 - Bad request
  {   
     "code":"invalid-request",
     "message":"Invalid request.",
     "validationErrors":[      {
           "code":"violation-on-type",
           "reason":"type must be MSISDN"
        }
     ]
  } 						

• Expected OTT Behaviour: The notification fails, and the user does not receive the message.

Revision History

Version	Description
2020.08	Added this topic.