Direct Carrier Billing Premium SMS Payment Widget DCB DCB Introduction Payment Flow Types Operations Callbacks Response Result Codes Session States Transaction States GSM CHARACTER SET GSM Character Set DCB Introduction Direct Carrier Billing HTTP API enables authorized Customers (Service Providers) to perform billing for services offered to mobile users on mobile or desktop web portals. It is recommended to integrate the API while consulting with Service Program documents provided by NTH technical team during service setup. History Date Changes 2021-05-01 Initial version Terminology Term Description Mobile Payment Gateway (MPG) NTH system designed to be interconnection between Mobile Network Operator (MNO) and Service Provider in payment process. Customer (Service Provider) NTH business partner/client that provides services to end users (in other words: Service Provider). End user Owner of a mobile device and/or consumer of services provided by a Service Provider. Mobile network operator (MNO) A telephone company that provides services for mobile phone subscribers. Service program An NTH document that describes exact service flow and defines a set of rules service must comply with. Service program documents are available for each specific market (country/operators) and shared with Service Providers during service setup. For more details about Service Programs, Customer should consult with assigned Account Manager. Customer Account Main Customer administrative element, it allows a Customer to authenticate to MPG with credentials and be granted authorization to access it. Also, certain default service configuration can be set up in an Account. Portal Customer’s mobile or desktop internet portal which contains service intended to be offered to End users who visit it. Payment user Mobile Payment Gateway end user record containing end user identity information, used with mobile internet flow. Payment session Mobile Payment Gateway session record tracking complete payment process including authorization and payment(s), and eventually subscription termination for subscription services. Payment transaction Mobile Payment Gateway transaction record, belonging to a session and representing one specific charging event. Notification Mobile Payment Gateway notification record notifying Customer about Payment session and Payment transaction events and status changes. Request format Direct Carrier Billing HTTP API is implemented as a standard HTTP service. All operations and callbacks are issued with HTTP POST requests containing parameter query in request body. Content-Type header should be set to application/x-www-form-urlencoded, while parameter query should be URL encoded and composed of parameters with associated values separated by equals sign (=). All such parameter=value pairs must be connected with standard HTTP GET/POST concatenation character ampersand (&). Default text encoding used is UTF-8. Response format Customer's application sends commands as HTTP POST requests and receives back responses formatted as XML or JSON. Response formatting depends on Customer preferences and can be controlled through HTTP request Accept header: if Customer sends HTTP request with Accept header set to application/xml - the response will be formatted in XML format if Customer sends HTTP request with Accept header set to application/json - the response will be formatted in JSON format Default response is in XML format. Customer's responses to callbacks are expected to return only HTTP response code 200, without response body payload. Besides direct HTTP calls of API commands, HTTP end user redirections also are used in particular parts of service payment procedure. Concurrent HTTP connections limit By default, Customer is allowed to establish no more than 10 concurrent HTTP connections towards the MPG for capacity reasons. If Customer requires more concurrent connections, Account Manager should be contacted in order to ensure larger throughput. Prerequisites In order to be able to utilize Direct Carrier Billing HTTP API, Customer needs to acquire the following: Customer Account - account username and password provided by NTH during initial account setup. Service code - textual service code provided by NTH during initial service setup. Endpoint URL - MPG endpoint URL where API requests should be sent by the Customer. Provided by NTH during initial service setup. Service program - detailed document about specific service rules and implementation guidelines provided by NTH. Internet connection - either permanent or temporary. Application - capable of receiving and sending HTTP requests, a socket listening application or Perl/PHP/JSP/ASP script capable of receiving and sending HTTP requests. IP whitelist - Customer must provide IP addresses of servers from which HTTP requests will be sent, for access restrictions configuration. Payment flow types Depending on the end user's internet connection type while accessing Service Provider's portal and market restrictions, Customer may initiate one of the two main payment flow types: Mobile internet payment flow Web (wi-fi) internet payment flow Actual flow implementation varies between markets and is described in Service Program documents. Mobile internet payment flow From Customer's point of view, a typical mobile Internet payment flow consists of several phases as shown in image below. PHASE 1 - IDENTIFICATION: Portal discovery – end user discovers Customer's portal and initiates payment process on it by clicking on proper option. Identification - Customer initiates end user identification process by issuing wapIdentifyUser command towards MPG. Redirection – Customer redirects end user's browser to MPG where end user identification is conducted. End user has to be identified by MPG as eligible for this kind of payment (he/she has to be accessing the internet by using mobile internet connection of the operator). End user is redirected back to the Customer, followed by Customer fetching end user identity information. Following commands are supported by the API during Identification phase: Command name Purpose wapIdentifyUser Used to initiate end user identification process. getUser Fetching of identification status and user’s identity (if resolved). PHASE 2 - AUTHORIZATION AND PAYMENT: Authorization - Customer initiates end user authorization by issuing wapAuthorize / paymentAuthorize command towards MPG. Redirection to confirmation page - Customer redirects end user's browser to MPG where session processing takes place, followed by end user landing on a confirmation page which contains all information about service terms and conditions, asking end user to authorize payment by clicking on proper option. Acceptance of terms on confirmation page – end user has to confirm payment (authorization of payment) by clicking on accept payment option on confirmation page. Redirection to Customer - upon completing authorization steps, end user is redirected back from MPG to the Customer. Payment result - Result of the authorization and/or payment is delivered to the Customer, either by Customer fetching the result or via notification mechanism. Deliver content - once payment has been successfully completed and Customer notified about the result, Customer delivers content to the end user. Following commands are supported by the API during Authorization and Payment phase: Command name Purpose wapAuthorize Used to initiate authorization for previously successfully identified end user (accessing the internet via mobile internet connection of the operator). paymentAuthorize Used to initiate authorization of unspecified type, utilized in some markets (specified in Service Program documents). checkStatus Command used to check session status, primarily used for onetime services as only session status is returned. getSession Used by the Customer to fetch complete session information, regardless of the session type. It is recommended to use this command for all session retrieval purposes. getSubscription Similar to getSession command, returns session information but only for session of subscription type. preparePayment May be used in special cases by the Customer to manually initiate payment for a session. Not generally used. commitPayment Command used to commit previously successfully Reserved payment transaction. PHASE 3 - SUBSCRIPTION TERMINATION: Subscription termination request - On Customer's service portal, end user requests termination of a subscription. Close subscription - Customer issues closeSubscription request towards MPG to terminate subscription on MPG / MNO side. Following commands are supported by the API during Subscription termination phase: Command name Purpose closeSubscription Command used to terminate active subscription. Web (wi-fi internet) payment flow From Customer's point of view, a typical web (wi-fi internet) payment flow consists of several phases as shown in image below. PHASE 1 - AUTHORIZATION AND PAYMENT: Portal discovery – end user discovers Customer's portal and initiates payment process on it by clicking on proper option and/or by providing the msisdn. Authorization - Customer initiates end user authorization by issuing webAuthorize / smsAuthorize / paymentAuthorize command towards MPG. Redirection to confirmation page - Customer redirects end user's browser to MPG where session processing takes place, followed by end user landing on a confirmation page which contains all information about service terms and conditions, asking end user to authorize payment by entering received PIN code. Send validation PIN – validation PIN code is sent to the end user by MPG / MNO. Validate PIN - end users receives PIN code in SMS delivered to the mobile handset and enters the PIN code in appropriate field for validation. Redirection to Customer - upon completing authorization steps, end user is redirected back from MPG to the Customer. Payment result - Result of the authorization and/or payment is delivered to the Customer, either by Customer fetching the result or via notification mechanism. Deliver content - once payment has been successfully completed and Customer notified about the result, Customer delivers content to the end user. Following commands are supported by the API during Authorization and Payment phase: Command name Purpose webAuthorize Used to initiate authorization with PIN confirmation for end user accessing the portal. smsAuthorize Used to initiate authorization with SMS confirmation for end user accessing the portal, utilized in some markets (specified in Service Program documents). paymentAuthorize Used to initiate authorization of unspecified type, utilized in some markets (specified in Service Program documents). webValidatePin Customer sends this command to validate PIN code received from the end user. checkStatus Command used to check session status, primarily used for onetime services as only session status is returned. getSession Used by the Customer to fetch complete session information, regardless of the session type. It is recommended to use this command for all session retrieval purposes. getSubscription Similar to getSession command, returns session information but only for session of subscription type. preparePayment May be used in special cases by the Customer to manually initiate payment for a session. Not generally used. commitPayment Command used to commit previously successfully Reserved payment transaction. PHASE 2 - SUBSCRIPTION TERMINATION: Subscription termination request - On Customer's service portal, end user requests termination of a subscription. Close subscription - Customer issues closeSubscription request towards MPG to terminate subscription on MPG / MNO side. Following commands are supported by the API during Subscription termination phase: Command name Purpose closeSubscription Command used to terminate active subscription. Operations This sections describes all operations available in Direct Carrier Billing HTTP API. Initiate user identification Issue wapIdentifyUser request to initiate end user identification process. HEADER PARAMETERS Accept string Default: application/xml Enum: "application/json" "application/xml" Customer may specify operation response format (json or xml) through this header. REQUEST BODY SCHEMA: application/x-www-form-urlencoded command required string non-empty Value: "wapIdentifyUser" username required string non-empty Customer account username (for authentication purposes). password required string non-empty Customer account password (for authentication purposes). serviceCode required string non-empty Code assigned to this particular service. userIp required string <ipv4> non-empty User's current IP address, in IPV4 format. callbackUrl required string <uri> URL to the Customer, to which MPG redirects the user after user identification. The callback URL may be dynamic and contain custom query parameters. MPG will append only query parameter uid=[uid] and will not modify other query parameters already present in the URL. Responses 200 Operation completed POST / Request samples Payload Content type application/x-www-form-urlencoded Copy command=wapIdentifyUser&username=user1&password=pass1&serviceCode=CH010001&userIp=127.0.0.1&callbackUrl=https%3A%2F%2Fexample.com%2Fcallback Response samples 200 Content type application/json Copy Expand all Collapse all { "resultCode": 100, "resultText": "OK", "uid": "12345", "operatorCode": "22801", "redirectUrl": "https://mpg.nth-mobile.com/user/12345" } Get user information Issue getUser request to fetch user identity information. HEADER PARAMETERS Accept string Default: application/xml Enum: "application/json" "application/xml" Customer may specify operation response format (json or xml) through this header. REQUEST BODY SCHEMA: application/x-www-form-urlencoded command required string non-empty Value: "getUser" username required string non-empty Customer account username (for authentication purposes). password required string non-empty Customer account password (for authentication purposes). serviceCode required string non-empty Code assigned to this particular service. uid required integer >= 1 Unique user identification ID received in response to wapIdentifyUser request. Responses 200 Operation completed POST / Request samples Payload Content type application/x-www-form-urlencoded Copy command=getUser&username=user1&password=pass1&serviceCode=CH010001&uid=12345 Response samples 200 Content type application/json Copy Expand all Collapse all { "resultCode": 100, "resultText": "OK", "user": { "status": "Identified", "userIp": "127.0.0.1", "msisdn": "00414411112222", "operatorCode": "22801" } } Initiate mobile internet authorization Issue wapAuthorize request to initiate authorization for previously successfully identified mobile internet end user. HEADER PARAMETERS Accept string Default: application/xml Enum: "application/json" "application/xml" Customer may specify operation response format (json or xml) through this header. REQUEST BODY SCHEMA: application/x-www-form-urlencoded command required string non-empty Value: "wapAuthorize" username required string non-empty Customer account username (for authentication purposes). password required string non-empty Customer account password (for authentication purposes). serviceCode required string non-empty Code assigned to this particular service. uid required integer >= 1 Unique user identification ID received in response to wapIdentifyUser request. price required integer >= 1 Message price in smallest currency unit (exact values will be provided by NTH). language string 2 characters Preferred end user language (in two-letter ISO 639-1 format). For example, en – English, de – German, etc. This parameter is optional, if omitted default language configured for the service will be used. callbackUrl string <uri> URL to the Customer, to which MPG redirects the end user once authorization processing is completed. The callback URL may be dynamic and contain custom query parameters. MPG will append only query parameter sessionId=[sessionId] and will not modify other query parameters already present in the URL. notificationUrl string <uri> URL where Customer wants to receive notifications about payment session status changes and conducted payment attempts for session in question. If this parameter is not provided, Customer will not receive any notifications. serviceUrl string <uri> Landing page URL where user started his interaction with the service and initiated payment. Important for end user complaint handling and operator compliance checks. authPage string Authorization page identifier, allows usage of multiple confirmation pages and campaign customization on a single service. Market dependant with more details available in Service Program documents. msisdn string <= 50 characters End user's mobile phone number. Used only in specical cases. operatorCode string [ 5 .. 6 ] characters End user's mobile network operator code. Used only in special cases. Responses 200 Operation completed Callbacks POST Session notification callbackPOST Recurrent transaction notification callbackPOST Transaction notification callback POST / Request samples Payload Content type application/x-www-form-urlencoded Copy command=wapAuthorize&username=user1&password=pass1&serviceCode=CH010001&uid=12345&price=100&callbackUrl=https%3A%2F%2Fexample.com%2Fcallback&notificationUrl=https%3A%2F%2Fexample.com%2Fnotification Response samples 200 Content type application/json Copy Expand all Collapse all { "resultCode": 100, "resultText": "OK", "sessionId": "CH010001x01x1571000000000", "operatorCode": "22801", "redirectUrl": "https://mpg.nth-mobile.com/session/CH010001x01x1571000000000" } Callback payload samples Callback POST: Session notification callback Content type application/x-www-form-urlencoded Copy command=deliverSessionState&serviceCode=CH010001&sessionId=CH010001x01x1571000000000&statusNumber=2&statusText=Payment+authorized&time=2021-01-01+12%3A00%3A00&notificationId=12345 Initiate authorization of unspecified type Issue paymentAuthorize request to initiate authorization of unspecified type for an end user. HEADER PARAMETERS Accept string Default: application/xml Enum: "application/json" "application/xml" Customer may specify operation response format (json or xml) through this header. REQUEST BODY SCHEMA: application/x-www-form-urlencoded command required string non-empty Value: "paymentAuthorize" username required string non-empty Customer account username (for authentication purposes). password required string non-empty Customer account password (for authentication purposes). serviceCode required string non-empty Code assigned to this particular service. price required integer >= 1 Message price in smallest currency unit (exact values will be provided by NTH). msisdn string <= 50 characters End user's mobile phone number entered into web form, in international format with leading zeros (for example: 00414411112222). Usage of the parameter is market dependant and described in Service Program documents. Usually, either msisdn or operatorCode parameter is used, but not both at the same time. uid integer >= 1 Unique user identification ID received in response to wapIdentifyUser request. Used only if end user identification was conducted prior to this operation. operatorCode string [ 5 .. 6 ] characters End user's mobile network operator code. Usage of the parameter is market dependant and described in Service Program documents. Usually, either msisdn or operatorCode parameter is used, but not both at the same time. callbackUrl string <uri> URL to the Customer, to which MPG redirects the end user once authorization processing is completed. The callback URL may be dynamic and contain custom query parameters. MPG will append only query parameter sessionId=[sessionId] and will not modify other query parameters already present in the URL. notificationUrl string <uri> URL where Customer wants to receive notifications about payment session status changes and conducted payment attempts for session in question. If this parameter is not provided, Customer will not receive any notifications. pinMessage string Text of a PIN message with placeholder ${pin} where PIN code will be inserted. If omitted, MPG will use default value configured for the service. If no default value is configured, this parameter must be sent in the request. Usage of the parameter is market dependant and described in Service Program documents. optinMessage string Text of opt-in confirmation request message. If omitted, MPG will use default value configured for the service. If no default value is configured, this parameter must be sent in the request. Usage of the parameter is market dependant and described in Service Program documents. embedded boolean Default: false Specifies if confirmation page should be embedded into Customer's portal page. Usage of the parameter is market dependant and described in Service Program documents. lang string 2 characters Preferred end user language (in two-letter ISO 639-1 format). For example, en – English, de – German, etc. This parameter is optional, if omitted default language configured for the service will be used. channel string Enum: "SMS" "WEB" "WAP" "INAPP" "UNSPECIFIED" Can be used to force confirmation channel for a session. Usage of the parameter is market dependant and described in Service Program documents. serviceUrl string Landing page URL where user started his interaction with the service and initiated payment. Important for end user complaint handling and operator compliance checks. authPage string Authorization page identifier, allows usage of multiple confirmation pages and campaign customization on a single service. Market dependant with more details available in Service Program documents. userIp string <ipv4> User's current IP address, in IPV4 format. Responses 200 Operation completed Callbacks POST Session notification callbackPOST Recurrent transaction notification callbackPOST Transaction notification callback POST / Request samples Payload Content type application/x-www-form-urlencoded Copy command=paymentAuthorize&username=user1&password=pass1&serviceCode=CH010001&msisdn=00414411112222&price=100&callbackUrl=https%3A%2F%2Fexample.com%2Fcallback&notificationUrl=https%3A%2F%2Fexample.com%2Fnotification Response samples 200 Content type application/json Copy Expand all Collapse all { "resultCode": 100, "resultText": "OK", "sessionId": "CH010001x01x1571000000000", "operatorCode": "22801", "redirectUrl": "https://mpg.nth-mobile.com/session/CH010001x01x1571000000000", "extraData": "" } Callback payload samples Callback POST: Session notification callback Content type application/x-www-form-urlencoded Copy command=deliverSessionState&serviceCode=CH010001&sessionId=CH010001x01x1571000000000&statusNumber=2&statusText=Payment+authorized&time=2021-01-01+12%3A00%3A00&notificationId=12345 Initiate web (wi-fi) authorization Issue webAuthorize request to initiate PIN confirmation authorization for an end user. HEADER PARAMETERS Accept string Default: application/xml Enum: "application/json" "application/xml" Customer may specify operation response format (json or xml) through this header. REQUEST BODY SCHEMA: application/x-www-form-urlencoded command required string non-empty Value: "webAuthorize" username required string non-empty Customer account username (for authentication purposes). password required string non-empty Customer account password (for authentication purposes). serviceCode required string non-empty Code assigned to this particular service. price required integer >= 1 Message price in smallest currency unit (exact values will be provided by NTH). msisdn string <= 50 characters End user's mobile phone number entered into web form, in international format with leading zeros (for example: 00414411112222). Usage of the parameter is market dependant and described in Service Program documents. Usually, either msisdn or operatorCode parameter is used, but not both at the same time. operatorCode string [ 5 .. 6 ] characters End user's mobile network operator code. Usage of the parameter is market dependant and described in Service Program documents. Usually, either msisdn or operatorCode parameter is used, but not both at the same time. callbackUrl string <uri> URL to the Customer, to which MPG redirects the end user once authorization processing is completed. The callback URL may be dynamic and contain custom query parameters. MPG will append only query parameter sessionId=[sessionId] and will not modify other query parameters already present in the URL. notificationUrl string <uri> URL where Customer wants to receive notifications about payment session status changes and conducted payment attempts for session in question. If this parameter is not provided, Customer will not receive any notifications. pinMessage string Text of a PIN message with placeholder ${pin} where PIN code will be inserted. If omitted, MPG will use default value configured for the service. If no default value is configured, this parameter must be sent in the request. Usage of the parameter is market dependant and described in Service Program documents. language string 2 characters Preferred end user language (in two-letter ISO 639-1 format). For example, en – English, de – German, etc. This parameter is optional, if omitted default language configured for the service will be used. serviceUrl string <uri> Landing page URL where user started his interaction with the service and initiated payment. Important for end user complaint handling and operator compliance checks. authPage string Authorization page identifier, allows usage of multiple confirmation pages and campaign customization on a single service. Market dependant with more details available in Service Program documents. userIp string <ipv4> User's current IP address, in IPV4 format. Responses 200 Operation completed Callbacks POST Session notification callbackPOST Recurrent transaction notification callbackPOST Transaction notification callback POST / Request samples Payload Content type application/x-www-form-urlencoded Copy command=webAuthorize&username=user1&password=pass1&serviceCode=CH010001&msisdn=00414411112222&price=100&pinMessage=Please+enter+%24%7Bpin%7D+code+to+confirm+payment Response samples 200 Content type application/json Copy Expand all Collapse all { "resultCode": 100, "resultText": "OK", "sessionId": "CH010001x01x1571000000000", "operatorCode": "22801", "redirectUrl": "https://mpg.nth-mobile.com/session/CH010001x01x1571000000000" } Callback payload samples Callback POST: Session notification callback Content type application/x-www-form-urlencoded Copy command=deliverSessionState&serviceCode=CH010001&sessionId=CH010001x01x1571000000000&statusNumber=2&statusText=Payment+authorized&time=2021-01-01+12%3A00%3A00&notificationId=12345 Initiate SMS authorization Issue smsAuthorize request to initiate SMS confirmation authorization for an end user. HEADER PARAMETERS Accept string Default: application/xml Enum: "application/json" "application/xml" Customer may specify operation response format (json or xml) through this header. REQUEST BODY SCHEMA: application/x-www-form-urlencoded command required string non-empty Value: "smsAuthorize" username required string non-empty Customer account username (for authentication purposes). password required string non-empty Customer account password (for authentication purposes). serviceCode required string non-empty Code assigned to this particular service. price required integer >= 1 Message price in smallest currency unit (exact values will be provided by NTH). msisdn required string [ 5 .. 50 ] characters End user's mobile phone number entered into web form, in international format with leading zeros (for example: 00414411112222). operatorCode string [ 5 .. 6 ] characters End user's mobile network operator code, can be used to force authorization over specific MNO. Usage of the parameter is market dependant and described in Service Program documents. notificationUrl string <uri> URL where Customer wants to receive notifications about payment session status changes and conducted payment attempts for session in question. If this parameter is not provided, Customer will not receive any notifications. optinMessage string Text of opt-in confirmation request message. If omitted, MPG will use default value configured for the service. If no default value is configured, this parameter must be sent in the request. Usage of the parameter is market dependant and described in Service Program documents. language string 2 characters Preferred end user language (in two-letter ISO 639-1 format). For example, en – English, de – German, etc. This parameter is optional, if omitted default language configured for the service will be used. serviceUrl string <uri> Landing page URL where user started his interaction with the service and initiated payment. Important for end user complaint handling and operator compliance checks. authPage string Authorization page identifier, allows usage of multiple confirmation pages and campaign customization on a single service. Market dependant with more details available in Service Program documents. userIp string <ipv4> User's current IP address, in IPV4 format. Responses 200 Operation completed Callbacks POST Session notification callbackPOST Recurrent transaction notification callbackPOST Transaction notification callback POST / Request samples Payload Content type application/x-www-form-urlencoded Copy command=smsAuthorize&username=user1&password=pass1&serviceCode=CH010001&msisdn=00414411112222&price=100&optinMessage=Reply+with+YES+to+confirm+payment Response samples 200 Content type application/json Copy Expand all Collapse all { "resultCode": 100, "resultText": "OK", "sessionId": "CH010001x01x1571000000000", "operatorCode": "22801" } Callback payload samples Callback POST: Session notification callback Content type application/x-www-form-urlencoded Copy command=deliverSessionState&serviceCode=CH010001&sessionId=CH010001x01x1571000000000&statusNumber=2&statusText=Payment+authorized&time=2021-01-01+12%3A00%3A00&notificationId=12345 Validate PIN code Issue webValidatePin request to initiate PIN validation for a session. HEADER PARAMETERS Accept string Default: application/xml Enum: "application/json" "application/xml" Customer may specify operation response format (json or xml) through this header. REQUEST BODY SCHEMA: application/x-www-form-urlencoded command required string non-empty Value: "webValidatePin" username required string non-empty Customer account username (for authentication purposes). password required string non-empty Customer account password (for authentication purposes). serviceCode required string non-empty Code assigned to this particular service. sessionId required string non-empty Unique session ID received in authorization response. pin required string [ 1 .. 20 ] characters PIN code that user enters into web form. Responses 200 Operation completed POST / Request samples Payload Content type application/x-www-form-urlencoded Copy command=webValidatePin&username=user1&password=pass1&serviceCode=CH010001&sessionId=CH010001x01x1571000000000&pin=1234 Response samples 200 Content type application/json Copy Expand all Collapse all { "resultCode": 100, "resultText": "OK" } Check session status Issue checkStatus request to fetch session state. In case authorization process included redirection to MPG and/or MNO, once processing is completed MPG appends sessionId=[sessionId] to callbackUrl Customer provided in an authorize request and redirects end user's browser to this URL. Then, Customer may fetch session state by issuing this command. Primarily used for onetime services as only session state is returned. HEADER PARAMETERS Accept string Default: application/xml Enum: "application/json" "application/xml" Customer may specify operation response format (json or xml) through this header. REQUEST BODY SCHEMA: application/x-www-form-urlencoded command required string non-empty Value: "checkStatus" username required string non-empty Customer account username (for authentication purposes). password required string non-empty Customer account password (for authentication purposes). serviceCode required string non-empty Code assigned to this particular service. sessionId required string non-empty Unique session ID received in authorization response. Responses 200 Operation completed POST / Request samples Payload Content type application/x-www-form-urlencoded Copy command=checkStatus&username=user1&password=pass1&serviceCode=CH010001&sessionId=CH010001x01x1571000000000 Response samples 200 Content type application/json Copy Expand all Collapse all { "resultCode": 100, "resultText": "OK", "statusNumber": 2, "statusText": "Payment authorized" } Get session information Issue getSession request to retrieve session information for a particular payment session. HEADER PARAMETERS Accept string Default: application/xml Enum: "application/json" "application/xml" Customer may specify operation response format (json or xml) through this header. REQUEST BODY SCHEMA: application/x-www-form-urlencoded command required string non-empty Value: "getSession" username required string non-empty Customer account username (for authentication purposes). password required string non-empty Customer account password (for authentication purposes). serviceCode required string non-empty Code assigned to this particular service. sessionId required string non-empty Unique session ID received in authorization response. Responses 200 Operation completed POST / Request samples Payload Content type application/x-www-form-urlencoded Copy command=getSession&username=user1&password=pass1&serviceCode=CH010001&sessionId=CH010001x01x1571000000000 Response samples 200 Content type application/json Copy Expand all Collapse all { "resultCode": 100, "resultText": "OK", "session": { "sessionId": "CH010001x01x1571000000000", "serviceCode": "CH010001", "sessionType": "subscription", "msisdn": "00414411112222", "operatorCode": "22801", "amountAuth": 100, "amountBilled": 500, "statusNumber": 2, "statusText": "Payment authorized", "recurrent": 1, "paymentType": "WAP", "timeOpen": "2021-01-01 12:00:00", "timeAuthorized": "2021-01-01 12:00:00", "timeRenewal": "2021-01-01 12:00:00", "timeExpiry": "2021-01-01 12:00:00", "timeClosed": "2021-01-01 12:00:00" } } Get subscription information Issue getSubscription request to retrieve subscription information for a particular payment subscription. HEADER PARAMETERS Accept string Default: application/xml Enum: "application/json" "application/xml" Customer may specify operation response format (json or xml) through this header. REQUEST BODY SCHEMA: application/x-www-form-urlencoded command required string non-empty Value: "getSubscription" username required string non-empty Customer account username (for authentication purposes). password required string non-empty Customer account password (for authentication purposes). serviceCode required string non-empty Code assigned to this particular service. msisdn string <= 50 characters End user's mobile phone number in international format with leading zeros (for example: 00414411112222). Either this or sessionId parameter is mandatory. sessionId string non-empty Unique session ID received in authorization response. Either this or msisdn parameter is mandatory. Responses 200 Operation completed POST / Request samples Payload Content type application/x-www-form-urlencoded Copy command=getSubscription&username=user1&password=pass1&serviceCode=CH010001&msisdn=00414411112222 Response samples 200 Content type application/json Copy Expand all Collapse all { "resultCode": 100, "resultText": "OK", "subscription": { "subscriptionId": "CH010001x01x1571000000000", "serviceCode": "CH010001", "msisdn": "00414411112222", "operatorCode": "22801", "statusNumber": 2, "statusText": "Payment authorized", "recurrent": 1, "paymentType": "WAP", "timeOpen": "2021-01-01 12:00:00", "timeAuthorized": "2021-01-01 12:00:00", "timeRenewal": "2021-01-01 12:00:00" } } Initiate payment Issue preparePayment request to initiate charging for an authorized session. Not generally used as payment processing is conducted by MPG. HEADER PARAMETERS Accept string Default: application/xml Enum: "application/json" "application/xml" Customer may specify operation response format (json or xml) through this header. REQUEST BODY SCHEMA: application/x-www-form-urlencoded command required string non-empty Value: "preparePayment" username required string non-empty Customer account username (for authentication purposes). password required string non-empty Customer account password (for authentication purposes). serviceCode required string non-empty Code assigned to this particular service. sessionId required string non-empty Unique session ID received in authorization response. price integer <int32> >= 0 Billing price in smallest currency unit (exact values will be provided by NTH). If this parameter is not set then authorization price will be used. In case it is set then the price needs to be less than or equal to that from authorization request. messageText string Message text which will be sent to the end user (e.g. when payment is made by premium SMS). In case of SMS, message itself can be up to 160 characters long and may contain only standard GSM characters. notificationUrl string <uri> URL where customer wants to receive notifications about payment transaction status changes. Overrides notificationUrl used in authorization request (stored in a session record). Responses 200 Operation completed Callbacks POST Transaction notification callback POST / Request samples Payload Content type application/x-www-form-urlencoded Copy command=preparePayment&username=user1&password=pass1&serviceCode=CH010001&sessionId=CH010001x01x1571000000000 Response samples 200 Content type application/json Copy Expand all Collapse all { "resultCode": 100, "resultText": "OK", "trid": 12345 } Callback payload samples Callback POST: Transaction notification callback Content type application/x-www-form-urlencoded Copy command=deliverTransactionState&serviceCode=CH010001&sessionId=CH010001x01x1571000000000&trid=12345&statusNumber=2&statusText=Charged&msisdn=00414411112222&time=2021-01-01+12%3A00%3A00&notificationId=12345 Commit payment Issue commitPayment request to commit successfully reserved payment transaction. Not generally used as payment processing is conducted by MPG. HEADER PARAMETERS Accept string Default: application/xml Enum: "application/json" "application/xml" Customer may specify operation response format (json or xml) through this header. REQUEST BODY SCHEMA: application/x-www-form-urlencoded command required string non-empty Value: "commitPayment" username required string non-empty Customer account username (for authentication purposes). password required string non-empty Customer account password (for authentication purposes). serviceCode required string non-empty Code assigned to this particular service. trid required integer <int64> >= 1 Unique payment transaction ID received in preparePayment response. Responses 200 Operation completed POST / Request samples Payload Content type application/x-www-form-urlencoded Copy command=commitPayment&username=user1&password=pass1&serviceCode=CH010001&trid=12345 Response samples 200 Content type application/json Copy Expand all Collapse all { "resultCode": 100, "resultText": "OK", "msisdn": "00414411112222" } Close subscription Issue closeSubscription request to initiate subscription termination on MPG and/or MNO side. HEADER PARAMETERS Accept string Default: application/xml Enum: "application/json" "application/xml" Customer may specify operation response format (json or xml) through this header. REQUEST BODY SCHEMA: application/x-www-form-urlencoded command required string non-empty Value: "closeSubscription" username required string non-empty Customer account username (for authentication purposes). password required string non-empty Customer account password (for authentication purposes). serviceCode required string non-empty Code assigned to this particular service. sessionId string non-empty Unique session ID received in authorization response. Either this parameter or subscriptionId is mandatory. subscriptionId string non-empty Unique session ID received in authorization response. Either this parameter or sessionId is mandatory. Responses 200 Operation completed POST / Request samples Payload Content type application/x-www-form-urlencoded Copy command=closeSubscription&username=user1&password=pass1&serviceCode=CH010001&sessionId=CH010001x01x1571000000000 Response samples 200 Content type application/json Copy Expand all Collapse all { "resultCode": 100, "resultText": "OK" } Callbacks Notifications for sessions and transactions are sent as HTTP callbacks to notificationUrl MPG receives in authorization or payment operation requests. Session notification callback Webhook If Customer provides notificationUrl in authorization request then MPG sends a notification about each session status change. If billing is conducted by MPG/MNO, same URL is used for delivery of transaction notifications. Customer should return HTTP response code 200 as indication of successfully received notification. All other response codes will result in notification resending until notification is delivered or until notification validity expires. REQUEST BODY SCHEMA: application/x-www-form-urlencoded command string Value: "deliverSessionState" serviceCode string Code assigned to this particular service. notificationId string Unique ID assigned to this particular notification. time string Notification creation datetime, in format yyyy-MM-dd HH:mm:ss, CET timezone. It should be used for correct notification processing order (newer notifications should override older ones which can be discarded). sessionId string Unique ID assigned to this particular payment session, as received in response to authorize command. statusNumber string Payment session status (see Session states for more information). statusText string Text explaining the status number in more detail. Responses 200 Notification successfully delivered Request samples Payload Content type application/x-www-form-urlencoded Copy command=deliverSessionState&serviceCode=CH010001&sessionId=CH010001x01x1571000000000&statusNumber=2&statusText=Payment+authorized&time=2021-01-01+12%3A00%3A00&notificationId=12345 Transaction notification callback Webhook This type of notification is sent for onetime services transactions and subscription services transactions created with preparePayment operation. Customer should return HTTP response code 200 as indication of successfully received notification. All other response codes will result in notification resending until notification is delivered or until notification validity expires. REQUEST BODY SCHEMA: application/x-www-form-urlencoded command string Value: "deliverTransactionState" serviceCode string Code assigned to this particular service. notificationId string Unique ID assigned to this particular notification. time string Notification creation datetime, in format yyyy-MM-dd HH:mm:ss, CET timezone. It should be used for correct notification processing order (newer notifications should override older ones which can be discarded). trid string Unique ID assigned to this particular payment transaction. amount string Amount which was billed. msisdn string End user's mobile phone number. If value is unknown this parameter will not be present. statusNumber string Payment transaction status (see Transaction states for more information). statusText string Text explaining the status number in more detail. sessionId string Unique ID assigned to this particular payment session, as received in response to authorize command. Request samples Payload Content type application/x-www-form-urlencoded Copy command=deliverTransactionState&serviceCode=CH010001&sessionId=CH010001x01x1571000000000&trid=12345&statusNumber=2&statusText=Charged&msisdn=00414411112222&time=2021-01-01+12%3A00%3A00&notificationId=12345 Recurrent transaction notification callback Webhook This type of notification is sent for subscription services transactions where MPG/MNO is conducting billing, including first transaction in a subscription. Customer should return HTTP response code 200 as indication of successfully received notification. All other response codes will result in notification resending until notification is delivered or until notification validity expires. REQUEST BODY SCHEMA: application/x-www-form-urlencoded command string Value: "recurrentPayment" serviceCode string Code assigned to this particular service. notificationId string Unique ID assigned to this particular notification. time string Notification creation datetime, in format yyyy-MM-dd HH:mm:ss, CET timezone. It should be used for correct notification processing order (newer notifications should override older ones which can be discarded). trid string Unique ID assigned to this particular payment transaction. amount string Amount which was billed. msisdn string End user's mobile phone number. If value is unknown this parameter will not be present. statusNumber string Payment transaction status (see Transaction states for more information). statusText string Text explaining the status number in more detail. subscriptionId string Unique ID assigned to this particular payment session of subscription type, as received in response to authorize command. Responses 200 Notification successfully delivered Request samples Payload Content type application/x-www-form-urlencoded Copy command=recurrentPayment&serviceCode=CH010001&subscriptionId=CH010001x01x1571000000000&trid=12345&amount=100&statusNumber=2&statusText=Charged&msisdn=00414411112222&time=2021-01-01+12%3A00%3A00&notificationId=12345 Response result codes Complete list of API response result codes with descriptions: Result code Result text Description 100 OK Used for each successfully made command execution. 150 Payment authorization in process Payment session authorization not completed, waiting for additional end user action. 151 Payment in process Transaction charging was successfully initiated and is currently in process. Used only for asynchronous charging. 152 Refund in process Transaction refund was successfully initiated and is currently in process. Used only for asynchronous refunding. 300 Payment authorization failure Payment session is not authorized but system is still allowing another end user action. For example, end user enters wrong PIN code in WEB payment authorization form and payment provider allows end user to retry again. 301 Payment authorization failed Payment authorization was unsuccessful. This result code indicates a failure occurred due to some unspecified reason. For more information, NTH can be contacted. 302 Payment authorization error Payment session authorization failed due to communication error with remote payment system. 303 Payment authorization expired Payment authorization process has expired. End user did not confirm authorization in predefined period. 311 Payment failed Transaction charging has failed. 312 Payment error Error is encountered during transaction charging. 313 Closing failed Payment session closing failed. 314 Refund failed Transaction refund has failed. 315 Insufficient funds The subscriber has insufficient funds for the requested transaction. 316 Subscriber temporary barred User is temporarily absent, e.g. his/her phone is switched off, he/she cannot be located on the network. 317 Subscriber permanently barred User is blacklisted or permanently barred by operator. 318 User blocked for adult services User blocked for adult services. 319 Cancel failed Cancelling payment authorization and/or transaction has failed. 320 Cancel error Error is encountered during payment authorization and/or transaction cancelling. 321 Charge to old for refund Refund has failed as charge/transaction is too old and cannot be refunded anymore. 400 Customer authorization failed Customer command rejected because of incorrect username and/or password, or account is not active. 401 Bad request Badly formatted customer request. 410 Required parameter '{parameter name}' missing Used when customer doesn't send some mandatory parameter. Tag {parameter name} will be replaced by the missing parameter name (e.g. Required parameter 'msisdn' missing). 411 Illegal value of parameter Used when some parameter value is not found (e.g. referenced user ID doesn't exist) or some parameter value is invalid (e.g. customer puts "*" in value of 'msisdn' parameter). 412 Too many HTTP connections active Returned if Customer has reached a concurrent HTTP connections limit set on account level. Customer should consult with Account Manager regarding increase of the limit and overall throughput. 422 Payment type not allowed Payment type not allowed for the service or user (for example if webAuthorize is called for WAP service, or user can't be billed over WAP channel) 424 Payment session closed. Payment session in question has been/is closed. 425 Session not authorized Payment session in question is not yet authorized, meaning operation (for example: charging) cannot be completed. 426 Session already authorized Payment session in question is already authorized, returned if Customer is trying to complete authorization for this session. 427 Transaction execution error Transaction execution error 428 Transaction already charged Transaction in question is already charged. Returned if Customer is trying to commit already charged transaction. 429 Unsupported destination Mobile payment not supported for the mobile operator or mobile operator not resolved for requested user. 431 Unidentified user User not identified (could not obtain msisdn). 432 Amount not authorized Returned if Customer is trying to charge end user for amount different from the amount user was authorized for. 433 Session of subscription type exists Payment session of subscription type already exists for a specified msisdn. 434 Payment rejected, limit reached. Payment authorization and/or charging rejected because end user reached a specific spending limit. 436 Subscription not found Payment session Customer is issuing request for is not found in the records. 437 Operation not supported Returned in case Customer is calling a method or operation not supported for a service/connection in question. 440 Direct operator payment not supported Direct operator payment not supported 441 Transaction already terminated Transaction already terminated 442 Requested service is inactive Requested service is inactive 443 User not provisioned for operator billing User not provisioned for operator billing 500 Internal server error Unhandled general error occurred during payment transaction processing. 501 Server configuration error Command failed due to system configuration error. Session states Payment session can have one of the following states: Status number Status text Description 0 Payment authorization in process Payment session authorization not completed, waiting for additional end user action. 1 Payment authorization failure Authorization process failure. Payment session is not authorized but system is still waiting for another user action. For example, user enters wrong PIN code during WEB payment authorization and payment provider allows user to retry again. 2 Payment authorized Payment session is authorized. 3 Payment session OnHold Payment subscription is currently in inactive status (last payment attempt failed). 4 Payment session closed Payment session has been closed. 5 Payment session cancelled Payment session has been cancelled on provider side but not yet closed. Specific to some markets. -1 Payment authorization failed, insufficient funds Payment authorization failed because user doesn't have enough funds on his account. -2 Payment authorization failed Payment authorization was unsuccessful. This status indicates a failure occurred due to some unspecified reason. For more information, NTH can be contacted. -3 Payment authorization error Payment session authorization failed due to communication error with remote payment system. -4 User rejected payment User rejected billing by clicking NO on payment confirmation page. -5 User blocked for adult services Payment authorization failed, user blocked for adult services. -6 Payment session closing failed Payment subscription closing failed. -7 Subscriber permanently barred User is permanently barred from using premium services, most often by mobile operators. -8 Subscriber temporary barred User is temporarily absent, e.g. his/her phone is switched off, he/she cannot be located on the network. -9 Subscriber spend limit exceeded User reached his spending limit and payment cannot be authorized. -10 Pin validation failed PIN validation failed for payment session. -11 Payment authorization expired Payment authorization failed since it expired or was not authorized on time (e.g. user did not accept payment on authorization page and decided to close browser). -12 Payment authorization failed, user already subscribed User already has another active subscription session for service in question. Transaction states Payment transaction can have one of the following states: Status number Status text Description 0 Charging in process Payment transaction charging is in process, used for asynchronous charging. 1 Reserved Payment transaction successfully reserved. 2 Charged Payment transaction successfully billed. 3 Refunded Transaction is refunded. Upon end user complaint, transactions can be refunded e.g. by customer care. 4 Canceled Payment transaction is cancelled. 5 Refund in process Payment transaction refund is in process, used for asynchronous refunding. -1 Charging failed, insufficient funds Payment failed because user doesn't have enough funds on his account. -2 Charging failed Payment transaction charging was unsuccessful. This status indicates a failure occurred due to some unspecified reason. For more information, NTH can be contacted. -3 Charging failed, subscriber spend limit exceeded Payment failed because user reached his spending limit. -4 Charging failed, subscriber temporary barred Payment failed because user is temporarily absent, e.g. his/her phone is switched off, he/she cannot be located on the network. -5 Charging error Payment transaction charging failed due to communication error with remote payment provider system or temporary operator network failure. -6 User blocked for adult services Payment transaction failed, user is blocked for adult services. -7 Cancel failed Payment cancelling failed. -8 Cancel error Payment cancelling failed with undefined error. -9 Charging failed, subscriber permanently barred Payment failed because user is permanently barred from using premium services, most often by mobile operators. -10 Cancel failed, subscriber permanently barred Payment transaction cancelling failed, due to an unspecified reason. GSM Character Set This section provides a table of all the characters supported by SMS. This is default character set supported by any mobile phone. Bits per character: 7 SMS User Data Length meaning: Number of characters CBS pad character: CR Basic Character Set 0x00 0x10 0x20 0x30 0x40 0x50 0x60 0x70 0x00 @ Δ SP 0 ¡ P ¿ p 0x01 £ _ ! 1 A Q a q 0x02 $ Φ " 2 B R b r 0x03 ¥ Γ # 3 C S c s 0x04 è Λ ¤ 4 D T d t 0x05 é Ω % 5 E U e u 0x06 ù Π & 6 F V f v 0x07 ì Ψ ' 7 G W g w 0x08 ò Σ ( 8 H X h x 0x09 Ç Θ ) 9 I Y i y 0x0A LF Ξ * : J Z j z 0x0B Ø ESC + ; K Ä k ä 0x0C ø Æ , < L Ö l ö 0x0D CR æ - = M Ñ m ñ 0x0E Å ß . > N Ü n ü 0x0F å É / ? O § o à LF is a Line Feed control. CR is a Carriage Return control, or filler. ESC is an Escape to extension table (maps to NBSP). SP is a Space character. Following table shows GSM 7-bit default alphabet extension table as defined in ETSI GSM 03.38. These characters can be used in standard SMS message without requiring special encoding, but count as 2 characters towards maximum text length due to the fact that each character from extended table requires two 7-bit bytes! Basic Character Set Extension 0x00 0x10 0x20 0x30 0x40 0x50 0x60 0x70 0x00 | 0x01 0x02 0x03 0x04 ^ 0x05 € 0x06 0x07 0x08 { 0x09 } 0x0A FF 0x0B SS2 0x0C [ 0x0D CR2 ~ 0x0E ] 0x0F \ FF is a Page Break control. If not recognized, it shall be treated like LF. CR2 is a control character. No language specific character shall be encoded at this position. SS2 is a second Single Shift Escape control reserved for future extensions. In case of message text longer than 140 bytes the SMS message should be segmented into more messages and encoded with a proper concatenation header. The concatenation header length with additional fill bits requires seven 7-bit bytes. Meaning, that each SMS concatenation part can have up to 153 characters.