SmsCoin Instructions

====== Premium Short Code ====== ===== 1. General info ===== “Premium Short Code” is an SMS traffic exchange platform created in order to solve demand for running new and advanced services not designed as part of SMSCOIN project. This platform developed since 2007 and now is capable to run a wide range of services with high volumes of transactions. System is capable to route traffic based on keywords and short codes, most services are activated immediately. Available services are regular MO-MT Premium SMS payments, MO- and Web-initiated subscriptions, sessions and new pay-by-click (PBC) service, also known as “Easy Billing”. 'STOP' broadcast is available for partners, who are interested in that feature. To make it easy to run different types of services on the same platform, all advanced services are configured and run in such a way, that from partner's point of view it looks like regular MO-MT traffic. Such approach enables setting up one simple protocol described below and using it for all the services available in the system, regardless of the country, billing type and the service itself. Two additional protocols are available to register/manage customers to web-initiated subscriptions and pay-by-click services. Both are relevant only in case you mean to use this services. ===== 2. Receiving messages ===== MO messages request processor (Result URL) receives the following parameters: ^Parameter ^ Type ^ Description^ | country | char(2) | Biliteral country code | | shortcode | char(16) | Phone number the message was sent to (short code) | | provider | char(32) | Mobile carrier (if relevant) | | billing | char(2) | Billing system that is used by mobile carrier (either MO or MT). See below further information about billing systems. | | cost_local_user | float | Message cost for end-user, in local currency (with or w/o VAT) | | cost_local | float | Message cost, in local currency (always w/o VAT) | | cost_usd |float | Message cost, USD (always w/o VAT, used in financial reports) | | phone | char(32) | Phone number (msisdn) the message was sent from, incl. country code; in some countries, subscriber's unique ID in the system is transferred instead of the actual phone number. (ex. Moldova) | | msgid | char(40) | Unique message ID | | sid | int | System service identifier | | content | char(160 | Message text | | sign_v1 | char(32) | MD5-hash of a string, consisting of **secret_code, country, shortcode, provider, billing, cost_local_user, cost_local, cost_usd, phone, msgid, sid** and **content** (in order) concatenated with double colon ("::") as a separator, where **secret_code** is your Agregator service secret code. | | mcc | char(3) | Country Mobile Code | | mnc | char(3)| Network Mobile Code | | subscription_id | int | ID of subscription, in case it is relevant | System expects to receive HTTP status 200 and non-empty HTTP body as correct answer. In other cases requests will be repeated several times with 1 minute delay. Additionally, all requests can be repeated manually upon demand. If the request processor (Result URL) is unavailable when sending request (i.e. HTTP-status of the reply differs from 200 OK), all relevant data is sent to your email in order to help in problems resolving. ===== 3. Sending messages ===== Script for sending messages is located at [URL provided upon service creation] and receives the following parameters: ^Parameter ^ Type ^ Mandatory^ Description^ | user | int | yes | Your system user ID (numeric ID, not username) | | from | char(20) | no | Phone number of message sender (basically short code) | | to | char(32) | no | Phone number of message recipient (international format, w/o + and 00) | | msgid | char(40) | yes | ID of the MO message you are replying to. Can be 0 in case of pay-by-click service. | | type | string | yes | Message type (either text or wap link, will result in regular message or wap link respectively) | | text | string | yes | Message text or wap link title (see above) | | link | string | no | An address the link should point to (applicable only if **type** equals wap link). | | checksum | char(32) | yes | MD5-hash of a string, consisting of **secret_code, user, from, to, msgid, type, text** and **link** (concatenated in that order), where **secret_code** is your Aggregator service secret code.| | partner_id | char(64) | no | ID of the message in partner's system, used as security feature to prevent double-billing. Requests with the same partner_id are ignored. Same ID passed back in DLRs. (see note below at 3.1) | | pbc | int | no | Switch for pay-by-click service, 1 = PBC, not set or 0 = not PBC | | price | decimal | no | Service specific: pay-by-click Tariff value to be billed, used only for countries where multi-tariff short codes are available. In other cases tariff is detected by short code itself. | | moco | int | no | Service specific: pay-by-click Switch for direct operators billing (Mobile Commerce) for PBC service, 1 = use direct billing, not set or 0 = use regular PSMS | | force_async | int | no | Force full async mode (see note below at 3.1) | | force_sync | int | no | Force synchronous mode even if service is configured to work in async mode (can be used for testing, better not to use for production). | Parameters can be transferred with either GET or POST query. If non mandatory parameters are not set, default values are used, with data stored in database for specific MO transaction. ==== 3.1 Possible answers from the system ==== Generally, response from XML looks like the example given below. <code> <response> <status>200</status> <description>1234567890</description> </response> </code> ^ Type^ Status ^ Description ^ Explanation^ | OK | 200 | 1234567890 | 1234567890 is a unique ID of MT message you receive in DLR as mt_id | | OK | 200 | Accepted | If using asynchronous mode of connection, no ID is returned from our system, partner_id parameter can be used instead to identify messages | | error | 400 | Currently you're unable to send bulk SMS. | You try to send bulk message and the service is not available for your account | | error | 403 | Error. checksum failed. | checksum parameter does not match one in our system | | error | 404 | No previous MO request found. | msgid parameter is missing or wrong. This parameter is mandatory for all the services except Pay-By-Click | | error | 409 | spent limit reached | Service specific: pay-by-click customer reached spent limit for current month | | error | 410 | phone not registered for a service | Service specific: pay-by-click msisdn provided not registered for a service (no active token for billing available)| | error | 500 | Server side error. | Some internal error occurred. In most cases it is the result of problem with uplink. | Please be aware, that statuses above is part of XML output and not HTTP status, in all cases HTTP status must be 200. If partner_id (with PBC) or force_async parameters passed, fully asynchronous mode enabled, processing of message put into queue and output will not contain ID of MT transaction but word 'Accepted' and will look like <code> <response> <status>200</status> <description>accepted</description> </response> </code> ===== 4. Receiving DLR (payment status) ===== ^Parameter ^ Type ^ Description^ | msgid | int | Unique MO message ID | | mt_id | int | Unique MT message ID (as received from XML response) | | phone | char(32) | Phone number the message was sent from, incl. country code; in some countries subscriber's unique ID in the system is transferred instead of actual phone number. | | status | char(16) | Message status (see below) | | sign_v1 | char(32) | MD5-hash of a string, consisting of **secret_code, msgid, mt_id, phone** and **status** (in that order) concatenated with double colon ("::") as a separator, where **secret_code** is your Agregator service secret code. | | partner_id | char(64) | ID of the message in partner's system, used as security feature to prevent double-billing. Used only for Pay-By-Click service. | ==== 4.1. Message statuses ==== For countries that employ MT billing system, message cannot be processed as long as its status is unknown (must be considered as 'accepted'). Message status can be one of the following: * **delivered** - the message was delivered; * **rejected** - user rejected the payment; * **failed** – the message was not delivered to the end user (billing failed); * **fraud** - the message was labeled as fraudulent. This status can be assigned even after successful delivery (i.e. upon disclosure). * **stop** – 'stop' broadcast status, any subscription service should be stopped. For countries that employ **MO** billing system, message is considered to be paid for by default, and the message status script is called only on **fraud** (see above).