Crediting Developer Guide

Credit request that is immediately successful

1. The content provider decides to make a credit to an end user's account and makes an HTTPS GET or POST request to the Charge To Account Gateway at:

   https://cta.mxtelecom.com/api/credit

   The end user's mobile number and the amount to be credited are sent as parameters to the request. The content provider's identity is verified with a username and password, also passed as parameters.

   This example shows the basic structure of a credit request:

   https://cta.mxtelecom.com/api/credit?username=yourname&password=yourpass&msisdn=447700900999&currency=GBP&amount=500

2. The Charge To Account Gateway checks the request for validity and against account credit limits, and if the checks pass, it returns a unique creditId in the API request response.

3. The Charge to Account Gateway submits a request to the network operator to credit the account. In this case, the network operator is able to immediately credit the end user's account, and confirms to the Charge To Account Gateway that the credit has been applied. The content provider may then decide to inform the end user that their account has been successfully credited. This is compulsory for some networks - please check with your account manager.

4. The Charge to Account Gateway makes an HTTP notification to the content provider indicating that the credit has been confirmed. Details of the notification can be found in Notification API. In this case the content provider receives a single notification with a creditState of confirmed; in other examples below, more than one notification with different creditState values may be sent.

Credit request featuring separate 'Submitted' and 'Confirmed' notifications

Some networks do not apply the credit immediately after submission. In this case MX Telecom will send two separate notifications to the content provider. The first is made when the credit request has been submitted and the second after the credit has been applied.

1. The content provider decides to make a credit to an end user's account and makes an HTTPS GET or POST request to the Charge To Account Gateway at:

   https://cta.mxtelecom.com/api/credit

   The end user's mobile number and the amount to be credited are sent as parameters to the request. The content provider's identity is verified with a username and password, also passed as parameters.

   This example shows the basic structure of a credit request:

   https://cta.mxtelecom.com/api/credit?username=yourname&password=yourpass&msisdn=447700900999&currency=GBP&amount=500

2. The Charge To Account Gateway checks the request for validity and against account credit limits, and if the checks pass, it returns a unique creditId in the API request response.

3. The Charge to Account Gateway makes a request to the network operator to credit the end user's mobile account. In this case the request is asynchronous and has been accepted, but not yet applied, by the operator.

4. The Charge to Account Gateway notifies the content provider that the credit has been submitted to the network operator. At this point, the content provider can choose to inform the end user that their account will be credited.

5. When the network applies a credit to the account, they confirm this with the Charge to Account Gateway, which notifies the content provider that the credit has been confirmed. The content provider may then decide to inform the end user that their account has been successfully credited. This is compulsory for some networks - please check with your account manager. Details of the notification can be found in Notification API.

Credit request rejected by Charge to Account Gateway

1. The content provider makes an HTTPS crediting request to the Charge to Account Gateway, which checks the request for validity and against account-specific and fraud detection limits. The request is rejected due to a malformed request or for breaching one of these limits.

2. The Charge to Account Gateway returns details of the error in the HTTP response. For more information see Format of response from server.

Credit request failed by Charge to Account Gateway

1. The content provider makes an HTTPS crediting request to the Charge to Account Gateway, which checks the request for validity and against account-specific and fraud detection limits.

2. The Charge To Account Gateway returns a unique creditId in the response.

3. The Charge to Account Gateway uses the mobile phone number to identify the end user's network, and determines that it is unable to credit an account on that network.

4. The Charge to Account Gateway notifies the content provider that the credit has failed. Details of the notification can be found in Notification API. At this point, the content provider may wish to inform the end user that there was an issue crediting the bill.

Credit failed by network operator

1. The content provider makes an HTTPS crediting request to the Charge to Account Gateway. This is checked for correctness and against required credit limits.

2. The Charge To Account Gateway returns a unique creditId in the response.

3. The Charge to Account Gateway submits a request to the network operator to credit the end user's account, but as the mobile number is invalid or the account is otherwise uncreditable, the network operator rejects the request.

4. The Charge to Account Gateway makes an HTTP notification to the content provider, indicating that the credit has failed. Details of the notification can be found in Notification API.