User Context API
Introduction
This API enables an application to get information about the user's context. This information can be categorized into different categories or datasets:
• Personal info: Information about the user
• Profile: information about user’s profile
• Access info: information about the network the user is using
• Terminal info: information about the user’s handset
Each one of the former datasets has several fields which may not be available in all countries:
Personal info
| Field | Description | Availability |
|---|---|---|
| Gender | Indicates user's gender | Spain |
Profile info
| Field | Description | Availability |
|---|---|---|
| userType | It indicates if the user is prepay or postpay. | UK, Germany |
| icb | It indicates whether the user has the icb (incomming call barring) service activated. | UK, Germany |
| ocb | It indicates whether the user has the ocb (outgoing call barring) service activated. | UK, Germany |
| language | It indicates the user's language. | Germany, Spain |
| parental Control | It indicates whether the user has some parental control restriction activated. Allowed values are: 'not active', 'active, low restriction'. 'active, high restriction' and 'active, very high restriction'. | UK, Germany |
| operatorId | It indicates the user's operator. Allowed values are: 'O2' and 'MOVISTAR' | UK, Germany, Spain |
| mmsStatus | It indicates whether the MMS service is activated for the user | Spain |
| segment | It indicates the segment the user belongs to, among the following values: 'Intensive Use', 'High Use', 'Regular Use' and 'Low Use'. | UK |
Access info
| Field | Description | Availability |
|---|---|---|
| accessType | It indicates the access network the user is connected to. Allowed values are: 'GSM', 'UMTS', 'GPRS' and 'WiFi'. | Spain |
| apn | It indicates the APN (Access Point Name) to which the user is connected to access to the Internet. | UK |
| roaming | It indicates whether the user is in roaming or in his home network. | Spain |
Terminal info
| Field | Description | Availability |
|---|---|---|
| brand | It indicates the user's handset brand. | UK, Spain |
| model | It indicates the user's handset model. | UK, Spain |
| version | It indicates the user's handset software version. | Spain |
| mms | It indicates whether the user's handset supports MMS. | Spain |
| ems | It indicates whether the user's handset supports EMS. | Spain |
| smart Messaging | It indicates whether the user's handset supports smart messages. | Spain |
| wap | It indicates whether the user's handset supports the WAP service. | Spain |
| ussd Phase | It indicates if the user's handset support USSD, and in that case, which USSD phase (Phase 1: only received USSD; Phase 2: interaction supported, allowing to answer to a received USSD). | Spain |
| ems Max Number | It indicates the maximum number of concatenated SMS allowed by the user's handset. | Spain |
| wap Push | It indicates whether the user's handset supports the WAP Push service. | Spain |
| mmsVideo | It indicates whether the user's handset is able to play video received over MMS. | Spain |
| video Streaming | It indicates whether the user's handset supports video streaming. | Spain |
| screen Resolution | It indicates the user's handset screen size. | UK |
Operations
The following is the description of all operations, data types and error codes related to User Context API. Data types are formally defined in the [User Context API XSDshttp://link_to_context_xsd].
GetUserInfo
Allows an application to get all the user context information in one shot.
Request
| Name | Description |
|---|---|
| URI |
https://api.bluevia.com/services/REST/Directory/{guid}/UserInfo?version=v1, https://api.bluevia.com/services/REST/Directory/{guid}/UserInfo?version=v1, https://api.bluevia.com/services/REST/Directory/{guid}/UserInfo?version=v1, https://api.bluevia.com/services/REST/Directory/{guid}/UserInfo?version=v1, where {guid} is the access token included in the Authorization header, preceded by the 'alias:' prefix. Optionally followed by 'alt=json' to request JSON format in the response. |
| HTTP method | GET |
| Authorization | OAuth |
| Body | none |
This operation can optionally include the dataSets parameter in the query string to filter datasets included in the response. Allowed values are:
• PersonalInfo, to filter by user's personal information.
• Profile, to filter by user's profile information.
• AccessInfo, to filter by information related to the network the user is using.
• TerminalInfo, to filter by user's handset information.
This parameter must include always three values separated by a comma.
A general user info request would be:
Response
| Name | Description |
|---|---|
| HTTP status | 200 OK |
| Body | userInfo element of type UserInfoType, formatted as XML or JSON (if 'alt=json' was included in the request). |
Note that not every field is always available for every user. It depends on the information BlueVia owns about the user.
The corresponding response
A successful response consists of a 200 OK HTTP status and a methodResponse element in the response body.
Types
MethodCallType
This type extends the base type MethodCallType defined in Common types (RPC) and has the following structure:
| Name | Type | Required | Description |
|---|---|---|---|
| method | MethodType | Y | It determines the operation actually being performed. |
| params | N | It contains one (or none) of the following elements, which are operation dependant parameters: |
| Name | Type | Operation |
|---|---|---|
| paymentParams | PaymentParamsType | Payment |
| getPaymentStatusParams | GetPaymentStatusParamsType | Get Payment Status |
| notifyPaymentFinalStatusParams | NotifyPaymentFinalStatusParamsType | Notify Payment Final Status |
MethodResponseType
This type extends the base type MethodResponseType defined in Common types (RPC) and has the following structure:
| Name | Type | Required | Description |
|---|---|---|---|
| result | N | It contains one (or none) of the following elements, which are operation dependant parameters: |
| Name | Type | Operation |
|---|---|---|
| paymentResult | PaymentResultType | Payment |
| getPaymentStatusResult | GetPaymentStatusResultType | Get Payment Status |
This enumeration has the following values:
| Value | Description |
|---|---|
| PAYMENT | Payment operation. |
| CANCEL_AUTHORIZATION | Cancel Authorization operation. |
| GET_PAYMENT_STATUS | Get Payment Status operation. |
| NOTIFY_PAYMENT_FINAL_STATUS | Notify Payment Final Status operation. |
PaymentParamsType
This type has the following structure:
| Name | Type | Required | Description |
|---|---|---|---|
| timestamp | dateTime | Y | Date and time when the payment is attempted. |
| paymentInfo | PaymentInfoType | Y | Product price, expressed as amount and currency. |
| receiptRequest | SimpleReferenceType | N | Used to request payment status notifications. |
PaymentInfoType
This type has the following structure:
| Name | Type | Required | Description |
|---|---|---|---|
| amount | unsignedInt | Y | The cost of the digital good being sold, expressed in the minimum fractional monetary unit of the considered currency (to avoid decimal digits). E.g. to express an amount of 1,99 €, this parameter will be '199' (i.e. 199 cents of Euro). |
| Currency | string | Y | The currency in which the amount is expressed, following ISO 4217 (EUR, GBP, MXN, etc.). This currency must match the one corresponding to the customer's country. |
PaymentResultType
This type has the following structure:
| Name | Type | Required | Description |
|---|---|---|---|
| transactionId | string | Y | Transaction identifier which uniquely identify the payment. |
| transactionStatus | TransactionEnumerationType | Y | It indicates the payment status. |
| transactionStatusDescription | string | Y | It contains further information related to the payment status. |
GetPaymentStatusParamsType
This type has the following structure:
| Name | Type | Required | Description |
|---|---|---|---|
| transactionId | string | Y | Transaction identifier corresponding with the payment operation whose status is requested. |
GetPaymentStatusResultType
This type has the following structure:
| Name | Type | Required | Description |
|---|---|---|---|
| transactionStatus | TransactionEnumerationType | Y | It indicates the payment status. |
| transactionStatusDescription | string | Y | It contains further information related to the payment status. |
NotifyPaymentFinalStatusParamsType
This type has the following structure:
| Name | Type | Required | Description |
|---|---|---|---|
| transactionId | string | Y | It indicates the transaction identifier for which the status is being notified. |
| transactionStatus | TransactionEnumerationType | Y | It indicates the payment status. |
| transactionStatusDescription | string | Y | It contains further information related to the payment status. |
TransactionEnumerationType
This enumeration has the following values:
| Value | Description |
|---|---|
| SUCCESS | The payment operation has been completed and the result is successful. The customer has been charged. |
| FAILURE | The payment operation has been completed but the result is unsuccessful. The customer has not been charged. |
| PENDING | The payment operation has not been completed yet. Ask again later. |
Error handling
Find below the error codes related to Payment API, following theBlueVia error formatYou might need also the full list of responses and generic error codes .
| HTTP status | Category | Id | Description |
|---|---|---|---|
| 400 | SVC | 1000 | Missing mandatory parameter |
| 400 | SVC | 1001 | Invalid parameter |
| 400 | SVC | 2 | Invalid parameter value |
| 400 | SVC | 3 | Invalid parameter value (element name). Possible values are (List of valid values) |
| 400 | SVC | 1002 | Requested URI does not exist |
| 400 | SVC | 1003 | Requested Operation does not exist |
| 400 | SVC | 1 | Generic Client Error |
| 400 | POL | 1004 | Requested version of API is deprecated |
| 400 | SVC | 1005 | Subscriber does not exist |
| 400 | SVC | 1006 | Resource does not exist |
| 400 | SVC | 1013 | Operation is not allowed |
| 400 | SVC | 3700 | Charge request failed when attempting it |
| 400 | SVC | 3701 | Invalid Currency or Virtual Units code |
| 400 | SVC | 3702 | Indicated taxes are invalid |
| 400 | SVC | 3703 | Invalid purchase code |
| 400 | SVC | 3704 | Invalid Transaction Id |
| 400 | POL | 1000 | Restricted Information |
| 400 | POL | 1001 | Requestors are not authorized |
| 400 | POL | 1002 | Access Token required |
| 400 | POL | 1003 | Session authentication not allowed to Consumer |
| 400 | POL | 3700 | Merchant is not allowed to apply taxes |
| 400 | POL | 3701 | This currency code is not allowed by the operator |
| 400 | POL | 3702 | Charge request exceeds the maximum limits allowed |
| 400 | SEC | 1000 | Invalid Consumer Id |
| 400 | SEC | 1001 | Invalid Consumer Signature. Consumer Authentication Failed |
| 400 | SEC | 1002 | Invalid or Missing Session Token. Consumer authentication failed |
| 400 | SEC | 1003 | Invalid Requestor |
| 400 | SEC | 1004 | Invalid Token |
| 400 | SEC | 1005 | Invalid Nonce |
| 400 | SEC | 1006 | Expired oAuth Token |
| 400 | SEC | 1007 | Expired Authentication Session |
| 400 | SEC | 1008 | Invalid Security Header |
| 400 | SVR | 1000 | Generic Service Error |
