Apply Credit

The Apply Credit operation enables you to add credit to an end user's mobile account.

Quick facts

Method

POST

Returns

Plain text or XML

Available

United Kingdom

Prerequisites

You must have Crediting provisioned with OpenMarket.

More information

See Mobile Crediting Overview.

Try It Out

Once you're provisioned with an OpenMarket account, you can try out the operation using cURL.

1. Create a text file for the POST body

Create a text file called apply-credit.txt and copy in the example below. You'll need to change the example phone number "447700900765" to a UK number one that you can receive messages on. Make sure that you include the country code; e.g. so that the number is in international format. Don't add a "+" character.

msisdn=447700900765&currency=GBP&amount=500&responseFormat=xml

2. Use cURL to send the message

Make a request using the following sample cURL. You'll need to replace the accountid:password with your OpenMarket account ID and password.

curl -s -D - -X POST  -H "Content-Type: application/x-www-form-urlencoded" --user accountid:password --data-binary @apply-credit.txt https://credit.openmarket.com/credit/v1/credit?

Response

For successful requests, OpenMarket sends an HTTP 200 response where the body contains information about the credit. The creditId uniquely identifies the request in our system.

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <outcome>success</outcome>
   <outcomeReasonId>1000</outcomeReasonId>
   <outcomeReasonText>Request was successful.</outcomeReasonText>
   <creditId>84282631</creditId>
</response>

Making a Request

Definition

POST https://credit.openmarket.com/credit/v1/credit?

Header fields

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

Example header

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

Field

Description

Authorization

Your account ID and password, separated by a colon, and then base64 encoded. Your account ID and password are case-sensitive. For help with Basic authentication see Authenticate with OpenMarket.

Content-Type

Specify application/x-www-form-urlencoded for this request.

Request body

The request body must contain the details for sending the message. You must format this similar to if you were sending the content as part of the URL.

Note: You can also choose to send the parameters in the URL as Query parameters.

Example request body

msisdn=447700900765&currency=GBP&amount=500&responseFormat=xml

Parameter

Description

amount

The amount to be credited in thousandths of the specified currency. This must be a positive integer, and the maximum value is 10000. For example, for £5 you would specify amount=5000.

You must ensure that your account supports each credit value you send; some values may need to be provisioned for some mobile operators.

Required: Yes

currency

A code denoting the currency you are crediting the end user in. The value must be a three letter ISO 4217 currency code; e.g. GBP for British Pounds Sterling.

Currencies are subject to account policy restrictions.

Required: Yes

msisdn

The mobile number of the end user being credited. This must be in international format with no leading "+" character. For example: 447700900750.

Required: Yes

brand

Pre-provisioned brand ID for accounts supporting multiple brands. See Brands.

Required: No

Default: if not specified, your default brand is used.

note

A descriptive note that is stored in the credit record. This is a text string up to 160 characters in length.

Required: No

Default: No default

responseFormat

The required response format. Either:

  • plain — Plain text format
  • xml — XML format

Required: No

Default: plain

smsContent

The message sent to the end user when the credit is applied.

End users connected to T-Mobile must receive a message, so if no message is specified, a default message is sent.

For end users connected to other mobile operators you can still send an SMS using this parameter. To do this, your account must be provisioned to always send a credit message, and you must also include the smsContent parameter. If no message is specified, then end users on these mobile operators will not receive a message.

Required: No

Default: The text "Your phone has been successfully credited".

subaccount

A subaccount that is stored in the credit record. This is a text string up to 10 characters in length. The subaccount does not need to already exist for the account.

Required: No

Default: no default

Example requests

The following GET request will credit the end user with £1.00 credit, and requests that the reply from OpenMarket is in XML:

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

msisdn=447700900765&currency=GBP&amount=1000&responseFormat=xml

This GET request will credit the end user and, once the credit is successfully applied, will send an SMS to the end user with the text "50p has now been credited to your account by ACME!":

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

msisdn=447700900999&currency=GBP&amount=500&smsContent=50p+has+now+been+credited+to+your+account+by+ACME%21

Response from OpenMarket

Accepted and rejected requests

OpenMarket responds to a successful request with an HTTP status code 200. The response body contains information about the credit including a creditId.

Plain text example

outcome:success
outcomeReasonId:1000
outcomeReasonText:Request was successful.
creditId:84282631

XML example

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <outcome>success</outcome>
   <outcomeReasonId>1000</outcomeReasonId>
   <outcomeReasonText>Request was successful.</outcomeReasonText>
   <creditId>84282631</creditId>
</response>

If the request is rejected (HTTP status code 403) or failed (HTTP status code 200), then the response body returned will indicate the issue.

Plain text example

outcome:rejected
outcomeReasonId:3108
outcomeReasonText:Invalid mobile phone number.

XML example

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <outcome>rejected</outcome>
   <outcomeReasonId>3108</outcomeReasonId>
   <outcomeReasonText>Invalid mobile phone number.</outcomeReasonText>
</response>

Field

Description

outcome

Result of the request. One of:

  • success
  • failed
  • rejected

Returned: Always

outcomeReasonId

Code defining the reason for the outcome of the request. This is a four-digit integer (e.g. 3210). See Response error codes below a list of the codes.

Returned: Always

outcomeReasonText

Natural language description of the outcome.

Returned: Always

creditId

Unique ID of the credit. This is a 64-bit unsigned integer; for example 69134308.

Returned: For successful requests

Testing your integration

OpenMarket provides an option for testing your integration with the production environment. See Testing Your Crediting Integration.

Troubleshooting

Unexpected characters in the response

If you receive unexpected characters in an HTTP response from OpenMarket, it may be because we are using "chunked" transfer coding, which is part of the HTTP 1.1 specification. These are normally stripped out by the browser or other transfer agent you are using. However, you may see these characters while connecting to OpenMarket via Telnet. You can ignore these characters if you see them.

Response error codes

When your system makes a request to OpenMarket, we indicates the outcome of the request in the HTTP response. The HTTP status code returned indicates the general outcome. The outcomeReasonId, included in the body of the response, indicated the specific outcome.

Success and failed outcomes with an HTTP status code of 200:

Code

Outcome

Description

1000

Success

The request was successful

4000

Failed

A technical error has occurred.

Retry your request. If you continue to receive this response, then contact OpenMarket Support for further help.

These error messages are returned in the response body when there was a problem with receiving the request.

Code

Outcome

Description

3037

Rejected

Missing amount.

3038

Rejected

Missing currency.

3108

Rejected

Invalid mobile phone number.

3113

Rejected

Invalid brand.

3137

Rejected

Invalid amount.

3163

Rejected

Brand does not support crediting.

3164

Rejected

Insufficient credit.

3165

Rejected

Maximum credit for that user is exceeded.

3172

Rejected

The mobile phone number is not configured as a test number for this account. An account can be provisioned with a list of "test numbers", and if this has been done, requests for any other number will fail with the above error code.

3200

Rejected

Invalid currency and amount combination according to account policy.