Making Mobile Crediting Requests

Your system connects to Mobile Crediting via an HTTPS interface. You can choose whether you'd like to receive responses from us as plain text or XML.

Requests are verified using HTTPS Basic Authentication, using the account ID and password provided by OpenMarket when you first provision Mobile Crediting.

To receive notifications from OpenMarket, you must also provide us with a notification URL. Notifications are made as HTTP or HTTPS POST requests to this URL.

Apply a credit to an end user's account

The following diagram shows the flow for an Apply Credit request.

  1. Your system makes an apply credit request via an HTTPS GET or POST request to OpenMarket. For example, the following POST request will credit the mobile number 447700900750 with £0.50 credit:

    POST /credit/v1/credit HTTP/1.1
Host: credit.openmarket.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

msisdn=447700900750&currency=GBP&amount=500
  2. OpenMarket checks the request is valid and returns an HTTP response that includes a unique credit ID.
  3. OpenMarket submits a request to the mobile operator to credit the account.

  4. The mobile operator credits the end user's account, and confirms to OpenMarket that the credit has been applied.

    OpenMarket sends a confirmation message to the end user at this point (see Confirming the credit with the end user).

  5. OpenMarket sends an HTTP GET notification to your system indicating that the credit has been confirmed (creditState=confirmed); for example:

    http://server.example.com/crediting?creditId=78858761&updateId=92647076&creditState=confirmed&date=2013-04-29+11%3A46%3A12+%2B0100&carrierid=348&msisdn=447700900750&billingType=prepay

Problems with applying credit

If there is a problem with the request or we cannot credit the end user, the request will be rejected or fail.

Rejected requests

OpenMarket checks requests for validity and against account-specific and fraud detection limits. If the request breaches one of these limits, or the request is malformed, OpenMarket will reject the request.

Failed requests

After a request is accepted, then OpenMarket may still fail the request. This can occur if the operator lookup fails or if the mobile operator does not support crediting, such as for non-UK or smaller mobile operators.

The end user's mobile operator may fail the message if the mobile number is now invalid or the account is otherwise uncreditable.

Credit request failed by OpenMarket

The following diagram shows the flow when a credit request is failed by OpenMarket.

  1. Your system makes an HTTPS GET or POST request to OpenMarket.
  2. OpenMarket returns a unique credit ID in the response.

  3. OpenMarket uses the mobile phone number to identify the end user's mobile operator, and determines that it is unable to credit an account on that mobile operator.

    OpenMarket notifies your system that the credit has failed:

    http://server.example.com/crediting?creditId=63944542&updateId=6451659&creditState=failed&date=2013-02-09+14%3A55%3A40+%2B0000&msisdn=447700900750&outcomeReasonId=50528518&outcomeReasonText=The+MSISDN+is+on+an+MVNO+that+does+not+support+Mobile+Crediting.

At this point, you could inform the end user that there was an issue crediting the bill.

Credit request failed by the mobile operator

The following diagram shows the flow when a credit request is failed by the mobile operator.

  1. Your system make an HTTPS GET or POST request to OpenMarket.
  2. OpenMarket returns a unique credit ID in the response.
  3. OpenMarket submits a request to the mobile operator to credit the end user's account.
  4. The mobile operator responds with a general indication of why the credit failed.

  5. OpenMarket makes an HTTP notification to your system, indicating that the credit has failed.

    http://server.example.com/crediting?creditId=63944542&updateId=6451659&creditState=failed&date=2013-02-09+14%3A55%3A40+%2B0000&msisdn=447700900750&outcomeReasonId=50528517&outcomeReasonText=The+MSISDN%EF%BF%BDs+billing+account+does+not+allow+credits.+For+example%2C+it+may+be+a+business+account.&carrierid=348

At this point, you could inform the end user that there was an issue crediting the bill.

Check your pre-paid balance

To check your pre-paid balance use the Get Credit Balance operation.

  1. Your system makes a credit balance request using an HTTPS GET to OpenMarket, for example:

    https://credit.openmarket.com/credit/v1/remainingCredit?brand=acme

    You must provide your authentication details using Basic authentication in the header.

  2. OpenMarket checks the request is valid and returns an HTTP response that includes your balance, for example:

    GBP,8745500