//[[restapi:start|RESTful API]]//

~~NOTOC~~

====== 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 [[:mmc_otto|ticketing tool]] | 123abcXYZ |
| signature | The unique [[restapi:appx_ciphering#HmacSHA512 - Cipher|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 |

<WRAP round tip>Used timestamp for signature should be the same as the header parameter</WRAP>

^ 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 <wrap info>Used in case it uses MT Billing Billers.</wrap> |
| 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) | 

<WRAP round tip>Parameters b64 (callback_b64,message_b64 and hints_b64) should be encoded in BASE_64</WRAP>

==== 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**.

<code json>

{
  "response":{ 
  "transactionid":"81686072599",
   "amount":"10.00",
   "hints":"aGludDE6dmFsdWUx=",
   "callback":"http://webservice.domain",
   "account":"1876XXXXXXX",
   "content":"Text message content",
   "status":"POSTED"}
}

</code>

== Result parameters ==

^ Parameter Name ^ Description ^ Example Values ^
| transactionid | The Id of the transaction. | 81686072599 |
| amount | Configured amount charged to account in configured currency. <wrap info>Please contact customer support for changing currency or to configure price.</wrap> | 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.

<code json>

{ "amount":10.0,
  "account":"1876XXXXXX",
  "status":"DENIED",
  "callback":"http://webservice.domain",
  "hints":"aGludDE6dmFsdWUx",
  "transaction-id":"81686072599540"}
</code>

^ 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.