Billing API
Overview
Charging a mobile number or “account” and deliver SMS with a text (Only for MT Billing).
URL
Parameters on the following URL are inside braces { }
http://backend17.ogangi.com:9020/orbit/api/bill/{account}/{amount}/{callback_b64}/{message_b64}/{hints_b64}
Security and Signature
In order to perform REST Calls on Orbit Billing API, signature and parameters should be provided on headers.
| Header Name | Description | Example |
|---|---|---|
| timestamp | current date-time in milliseconds format. | 123456789123 |
| publickey | Public Key provided by Ogangi Custom Team. please request it using our ticketing tool | 123abcXYZ |
| signature | The unique HmacSHA512 signature for this call, it's involve all input parameters. Generate it by ciphering the url: orbit/api/bill/{account}/{amount}/{callback_b64}/{message_b64}/{hints_b64}/timestamp with special private key | abcccer123xyz |
Used timestamp for signature should be the same as the header parameter
| Parameter Name | Description |
|---|---|
| account | An account or mobile number to charge Must use international prefix. |
| amount | Amount to charge to account. This parameter must be expressed in decimal notation, separated by “.”. |
| callback_b64 | Indicate web service in charge to receive billing status Used in case it uses MT Billing Billers. |
| message_b64 | Text message to be deliver to an account. |
| hints_b64 | Special parameters to help identify biller or to send relevant information. (Ex: param1:param1Info) |
Parameters b64 (callback_b64,message_b64 and hints_b64) should be encoded in BASE_64
Response
The Response JSON is divided in several fields showing, amount, account, hints, transaction status, url callback to post response and SMS content. Please note that there are several status for billing: ACCEPTED, DENIED, POSTED.
{
"response":{
"transactionid":"81686072599",
"amount":"10.00",
"hints":"aGludDE6dmFsdWUx=",
"callback":"http://webservice.domain",
"account":"1876XXXXXXX",
"content":"Text message content",
"status":"POSTED"}
}
Result parameters
| Parameter Name | Description | Example Values |
|---|---|---|
| transactionid | The Id of the transaction. | 81686072599 |
| amount | Configured amount charged to account in configured currency. Please contact customer support for changing currency or to configure price. | 10.00 |
| hints | Hints encripted in base64 | aGludDE6dmFsdWUx |
| callback | Web service to post billing status in base64 | aHR0cDovL3d3dy53ZWJzaXRlLmNvbQ== |
| account | Account or mobile number. | 1242xxxxxxx |
| content | Content of the message in base64 if account requires mt billing | Y29udGVudA== |
| status | The transaction status | POSTED,ACCEPTED,DENIED |
Billing Possible Status
| Status | Description |
|---|---|
| ACCEPTED | Transaction performed successfully |
| POSTED | Transaction was posted for billing, API sends a text message to account if billing was possible and a status update will be posted on requested webservice |
| DENIED | Billing for account or mobile number was REJECTED. |
| FORFEIT | Billing service took too long to receive a response - Used in MT Billing |
| ACCEPTED_WITH_DELAY | Transaction performed successfully but it took a long time to recieve response |
Billing Response
API or MT Billing will be used depending on Biller configuration, the response could be different depending which one is used.
API Billing Response
For API Billing configured Billers, status can only be ACCEPTED or DENIED.
MT Billing Response
For MT billing configured Billers, a response will be posted in the callback set in the request when billing status could be determined.
{ "amount":10.0,
"account":"1876XXXXXX",
"status":"DENIED",
"callback":"http://webservice.domain",
"hints":"aGludDE6dmFsdWUx",
"transaction-id":"81686072599540"}
| Parameter Name | Description | Example Values |
|---|---|---|
| hints | hints encripted in base64 | aGludDE6dmFsdWUx |
| callback | Web service for post billing status | http://webservice.domain |
| account | Account or mobile number. | 1876XXXXXX |
| status | The MT billing transaction status | ACCEPTED,FORFEIT,DENIED |
Setting New Billers
For configuring a new biller please contact Costumer Support team, with requested Price Points or amount to charge and which accounts patterns to set for billing.
