Voucher:Host-to-Host Specification
From Akorena Wiki
Contents |
Update
This page is considered obsolete. We will adopt open specification here http://code.google.com/p/openpulsa/wiki/Spesifikasi.
Overview
Spectra Voucher Top up Software (Spectra) provides main functions to top up balance of prepaid subscriber’s mobile phone.
Transaction Elements
Spectra will acts as transaction server while client system as transaction client. Reversed role might be required as of client system acts as transaction server while Spectra as transaction client.
Transaction Invocation Method
Spectra System Host to Host Gateway interface has been designed to allow simple, network-based communications between the Gateway and partner system.
TCP/IP is used as the carriage protocol. Partner's system has the option to disconnect the Gateway after each transaction completion, or maintain a permanent connection.
Each transaction will comprise of request and its corresponding response.
Transaction Protocols
Data exchange protocol will adopt XML-RPC protocol. XML-RPC is a Remote Procedure Calling protocol that works over the Internet. An XML-RPC message is an HTTP-POST request. The body of the request is in XML. A procedure executes on the server and the value it returns is also formatted in XML.
Complete specification and implementation list of XML-RPC is available at http://www.xmlrpc.com.
Response Code Definitions
Each transaction response contains response code indicating the status of transaction. The response code use similar convention used in HTTP status code.
Informational response code class indicated by 1xx code. 2xx class of status code indicates that the client's request was successfully received, understood, and accepted. The 4xx class of status code is intended for cases in which the client seems to have erred. Response status codes beginning with the digit "5" indicate cases in which the server is aware that it has erred or is incapable of performing the request.
Complete list of response code provided on Appendix A.
Function Interface
General Specification
| Password | Password will be assigned by Spectra System for each unique user name. |
| Naming Convention | Method call and its parameters are case sensitive |
| Response Code | Response code follow HTTP result code convention. Response code 2XX indicate normal transaction, 4XX indicate temporary failure, and 5XX indicate permanent failure. |
Heart Beat
| Method | samba.invoke |
| Description | This function is used to test the basic functionality of Spectra and the link condition between server and client. |
| Call Direction | Spectra acts as server |
Request Parameter
Parameter which must be defined in REQUEST are :
| Parameter | Description | Data Type | Example |
| Method | Called remote method | String(32) | heartbeat |
| Username | Partner's user name | String(16) | 27000050 |
Response Parameter
Values which must be defined in RESPONSE are :
| Parameter | Description | Data Type | Example |
| ResponseCode | Code of transaction result | Integer(3) | 200 |
| Time | Server time in ISO8601 format | yyyy-mm-ddTHH:MM:SS.SSSTZ | 2007-08-17T10:00:00.760+07:00 |
| Message | Response message | String(255) | Go Ahead! |
Top up
| Method | samba.invoke |
| Description | This function will top-up MSISDN by certain amount identified by its product code. |
| Call Direction | Spectra acts as server |
Request Parameter
Parameter which must be defined in REQUEST are :
| Parameter | Description | Data Type | Example |
| Method | Called remote method | String(32) | topup |
| Username | Partner's user name | String(16) | 27000050 |
| PIN | Personal Identification Number | String(8) | 1234 |
| MSISDN | Subscriber phone number | String(16) | 08888322366 or 628888322366 |
| ProductCode | Spectra System's voucher code | String(6) | A5 |
| ReferenceId | Client's unique transaction reference | String(32) | 098f6bcd46 |
Response Parameter
Values which must be defined in RESPONSE are :
| ResponseCode | Code of transaction result | Integer(3) | 200 |
| Parameter | Description | Data Type | Example |
| ReferenceId | Client's unique transaction reference (echoed) | String(32) | 098f6bcd46 |
| Time | Server time in ISO8601 format | yyyy-mm-ddTHH:MM:SS.SSSTZ | 2007-08-17T10:00:00.760+07:00 |
| Message | Response message | String(255) | SUKSES R5 ke 08888322366 070817-UxTesa Balance 95.350-5.200=90.150 |
| TransactionId | Spectra System server's unique transaction reference | String(32) | 070817-UxTesa |
| Price | Product's price | Float | 5200 |
| Balance | Account's balance | Float | 90150 |
Appendix A - Response Code
| Code | Message | Description |
| 200 | Success | The request has succeeded. The information returned with the response is dependent on the method used in the request. |
| 202 | Accepted | The request has been accepted for processing, but the processing has not been completed. |
| 400 | Bad Request | The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications. |
| 401 | Unauthorized | The request requires user authentication. The client MAY repeat the request with a suitable Authorization parameters. If the request already included Authorization credentials, then the 401 response indicates that authorization has been refused for those credentials. |
| 402 | Insufficient balance | The request could not be completed due insufficient balance |
| 403 | Forbidden | The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. |
| 404 | Product Not found | The request could not be completed due incorrect product code |
| 405 | Invalid MSISDN | The supplied MSISDN number is not valid. |
| 406 | Duplicate Request | The request could not be completed due duplicate request detected. Subscriber's MSISDN can be top up with certain product code only once within 12 hours. |
| 407 | Referenced Transaction ID not found | The server could not process request due referenced transaction Id was not found. |
| 408 | Product and MSISDN mismatch | The request could not be completed due mismatch between MSISDN and product code |
| 409 | Failed | Unknown error occurred |
| 410 | Temporary Error | The request could not be completed. The client SHOULD repeat the request. |
| 411 | Transaction Limit Reached | The request could not be completed due maximum limit of daily transaction reached. |
| 412 | Maintenance | The server currently under maintenance. |
| 500 | Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
| 503 | Service Unavailable | The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. |
| 520 | Connection Error | The server is currently unable to handle the request due network error |
| 521 | Data Integrity Error | The server is currently unable to handle the request due database error |
Appendix B - Timing
| Component | Bridge | XML-RPC server | Queue | Gateway |
| Timeout (secs) | 120 | 100 | 80 | 60 |
| Description |
