# Telebirr
This is a python helper package for Telebirr H5 Web payment integration helper. The use case for this interface is
payment via web. Third party system will invoke the interface upon payment issue by the customer and a redirect page
will be return to the third party system from telebirr platform.
## Logical specification
## Platform Authentication Rule
1. Telebirr platform allocate appId and appKey to the corresponding third party client. Each third party will have a
unique appId and appKey.
2. Third party source IP addresses should be added on the trust list. Those IP addresses of clients that are not in the
trust list will not access telebirr system.
3. The time of the timestamp is consistent with that of the server (within one minute). If they are inconsistent, the
access is considered illegal.
4. Check whether the signature entered by the client is consistent with the signature generated by the system. If they
are inconsistent, the access is considered illegal.
## Interface Description
|Parameter |Data Type | Mandatory or Optional |Description| Example|
|----------|----------|-----------------------|-----------|--------|
|appId |String |M |Indicates the appID provided from telebirr platform. It uniquely identify the third party.| ce83aaa3dedd42 ab88bd017ce1ca|
|appKey| String |M |Indicates the appKey provided by telebirr platform| a8955b02b5df475882038616d5448d43|
|nonce| String |M |Indicates a unique random string generated by third party system. The value of nonce for each request should be unique.| ER33419df678o8bb|
|notifyUrl| String |O |Indicates the end point URL from third party which will be used by telebirr platform to respond the Payment result. Telebirr platform uses this third party end point to proactively notify third party server for payment request result. If this parameter is empty, payment result notification will not be sent.| https://mmpay.trade.pay/notifyUrl/|
|outTradeNo| String |M |Indicates the third party payment transaction order number that will be generated by third party system and it shall be unique. Supported contents for outTradeNo parameter value is digits, letters, and underscores.| T0533111222S001114129|
|returnUrl| String |M |Indicates third party redirect page URL after the payment completed.| https://mmpay.trade.pay/T0533111222S001114129|
|shortCode| String |M |Indicates third party Short Code provided from telebirr.| 8000001|
|subject| String |M |Indicates the item or any other name for the payment that is being issued by the customer.
Note: Special characters such as /, =, & are not allowed.| Book|
|timeoutExpress| String |M |Indicates the payment Order request timeout from third party, which indicates the time for payment process to be ended. After this time the payment will not be processed and third party system can reinitiate again. Note: the parameter value unit is Minutes| 30|
|timestamp| String |M |Indicates the time stamp on the request message. The timestamp should be in milliseconds. Python codeļ¼`str(int(datetime.datetime.now().timestamp() * 1000))` Note: Use unix timestamp| 1624546517701|
|totalAmount| String |M |Indicates the order amount in ETB. The value ranges from 0.01 to 100000000.00 and is accurate to two decimal places. Note: The value will be authenticated by telebirr platform depending on the limit rule assigned to the customer. For instance, if the allowed daily limit transaction for a customer is 10,000 ETB then those transactions against this rule will be failed.| 9.00|
|receiveName| String |O |Indicates the transaction receiver name. | Ethiopian airlines|
## Interface Description
Response message element is described below
|Parameter |Data Type | Mandatory or Optional |Description| Example|
|----------|----------|-----------------------|-----------|--------|
|code |String |M |Indicates the Status Code for payment request| 0|
|msg |String |M |Indicates the Status Code Description for payment request| success|
|data |Object |M |Indicates the Data Object that consists the toPayURL| |
|toPayUrl |String |M |Indicates telebirr payment landing page URL to redirect the customer to H5 Web Payment. | https://h5pay.trade.pay/payId=RE9879T0972S|
## Getting started
` pip install telebirr `
```python
from telebirr import Telebirr
private_key = "YOUR PUBLIC KEY FORM TELEBIRR ADMIN"
telebirr = Telebirr(
app_id="YOUR APP ID FROM TELEBIRR ADMIN",
app_key="YOUR APP KEY FROM TELEBIRR ADMIN",
public_key=private_key,
notify_url="https://example.com/telebirr/121232",
receive_name="Your company name",
return_url="https://example.com/",
short_code="SHORT CODE FROM TELEBIRR ADMIN",
subject="Test",
timeout_express="30",
total_amount="10",
nonce="UNIQUE",
out_trade_no="UNIQUE"
)
response = telebirr.send_request()
```
## Decryption
After the payment is successfully completed telebirr will send you notification through the notification url
you have set on payment request. Here is how you can decrypt the payload coming from telebirr.
```python
from telebirr import Telebirr
public_key = "YOUR PUBLIC KEY FORM TELEBIRR ADMIN"
payload = "Payload coming from telebirr" // If you are using django it means request.body
decrypted_data = Telebirr.decrypt(public_key=public_key, payload=payload)
// Do what every you need to do with your data eg: update your order status
```
Raw data
{
"_id": null,
"home_page": "",
"name": "telebirr",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "python,telebirr,payment,ethiopia,ethio telecom",
"author": "Eba Alemayehu",
"author_email": "<ebaalemayhu3@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ec/3f/d53cfd2c83301708bccc842364b4a0216f44ee1fa8b9850c0965f800a9c3/telebirr-0.1.11.tar.gz",
"platform": null,
"description": "\n# Telebirr\n\nThis is a python helper package for Telebirr H5 Web payment integration helper. The use case for this interface is\npayment via web. Third party system will invoke the interface upon payment issue by the customer and a redirect page\nwill be return to the third party system from telebirr platform.\n\n## Logical specification\n\n![alt text](img/logical design.png \"Logical spacification\")\n\n## Platform Authentication Rule\n\n1. Telebirr platform allocate appId and appKey to the corresponding third party client. Each third party will have a\n unique appId and appKey.\n2. Third party source IP addresses should be added on the trust list. Those IP addresses of clients that are not in the\n trust list will not access telebirr system.\n3. The time of the timestamp is consistent with that of the server (within one minute). If they are inconsistent, the\n access is considered illegal.\n4. Check whether the signature entered by the client is consistent with the signature generated by the system. If they\n are inconsistent, the access is considered illegal.\n\n## Interface Description\n\n|Parameter |Data Type | Mandatory or Optional |Description| Example|\n|----------|----------|-----------------------|-----------|--------|\n|appId |String |M |Indicates the appID provided from telebirr platform. It uniquely identify the third party.| ce83aaa3dedd42 ab88bd017ce1ca|\n|appKey| String |M |Indicates the appKey provided by telebirr platform| a8955b02b5df475882038616d5448d43|\n|nonce| String |M |Indicates a unique random string generated by third party system. The value of nonce for each request should be unique.| ER33419df678o8bb|\n|notifyUrl| String |O |Indicates the end point URL from third party which will be used by telebirr platform to respond the Payment result. Telebirr platform uses this third party end point to proactively notify third party server for payment request result. If this parameter is empty, payment result notification will not be sent.| https://mmpay.trade.pay/notifyUrl/|\n|outTradeNo| String |M |Indicates the third party payment transaction order number that will be generated by third party system and it shall be unique. Supported contents for outTradeNo parameter value is digits, letters, and underscores.| T0533111222S001114129|\n|returnUrl| String |M |Indicates third party redirect page URL after the payment completed.| https://mmpay.trade.pay/T0533111222S001114129|\n|shortCode| String |M |Indicates third party Short Code provided from telebirr.| 8000001|\n|subject| String |M |Indicates the item or any other name for the payment that is being issued by the customer. \nNote: Special characters such as /, =, & are not allowed.| Book|\n|timeoutExpress| String |M |Indicates the payment Order request timeout from third party, which indicates the time for payment process to be ended. After this time the payment will not be processed and third party system can reinitiate again. Note: the parameter value unit is Minutes| 30|\n|timestamp| String |M |Indicates the time stamp on the request message. The timestamp should be in milliseconds. Python code\uff1a`str(int(datetime.datetime.now().timestamp() * 1000))` Note: Use unix timestamp| 1624546517701|\n|totalAmount| String |M |Indicates the order amount in ETB. The value ranges from 0.01 to 100000000.00 and is accurate to two decimal places. Note: The value will be authenticated by telebirr platform depending on the limit rule assigned to the customer. For instance, if the allowed daily limit transaction for a customer is 10,000 ETB then those transactions against this rule will be failed.| 9.00|\n|receiveName| String |O |Indicates the transaction receiver name. | Ethiopian airlines|\n\n## Interface Description\nResponse message element is described below\n\n|Parameter |Data Type | Mandatory or Optional |Description| Example|\n|----------|----------|-----------------------|-----------|--------|\n|code |String |M |Indicates the Status Code for payment request| 0|\n|msg |String |M |Indicates the Status Code Description for payment request| success|\n|data |Object |M |Indicates the Data Object that consists the toPayURL| |\n|toPayUrl |String |M |Indicates telebirr payment landing page URL to redirect the customer to H5 Web Payment. | https://h5pay.trade.pay/payId=RE9879T0972S|\n\n## Getting started\n\n` pip install telebirr `\n\n```python\nfrom telebirr import Telebirr\nprivate_key = \"YOUR PUBLIC KEY FORM TELEBIRR ADMIN\"\ntelebirr = Telebirr(\n app_id=\"YOUR APP ID FROM TELEBIRR ADMIN\",\n app_key=\"YOUR APP KEY FROM TELEBIRR ADMIN\",\n public_key=private_key,\n notify_url=\"https://example.com/telebirr/121232\",\n receive_name=\"Your company name\",\n return_url=\"https://example.com/\",\n short_code=\"SHORT CODE FROM TELEBIRR ADMIN\",\n subject=\"Test\",\n timeout_express=\"30\",\n total_amount=\"10\",\n nonce=\"UNIQUE\",\n out_trade_no=\"UNIQUE\"\n)\nresponse = telebirr.send_request()\n``` \n\n## Decryption\n\nAfter the payment is successfully completed telebirr will send you notification through the notification url \nyou have set on payment request. Here is how you can decrypt the payload coming from telebirr.\n\n\n```python\nfrom telebirr import Telebirr\npublic_key = \"YOUR PUBLIC KEY FORM TELEBIRR ADMIN\"\npayload = \"Payload coming from telebirr\" // If you are using django it means request.body\n\ndecrypted_data = Telebirr.decrypt(public_key=public_key, payload=payload)\n// Do what every you need to do with your data eg: update your order status\n``` \n",
"bugtrack_url": null,
"license": "",
"summary": "Telebirr integration",
"version": "0.1.11",
"split_keywords": [
"python",
"telebirr",
"payment",
"ethiopia",
"ethio telecom"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "080ba45d615c0320c7451bb5ab3a5874de70c4f87a746263c9c838d18f5be258",
"md5": "beda04e494f8b47568519b28bc36c790",
"sha256": "e722c6b533aa1f87c21071643cfb52e6649e6314f95c89a34a96884cf7909078"
},
"downloads": -1,
"filename": "telebirr-0.1.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "beda04e494f8b47568519b28bc36c790",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7096,
"upload_time": "2023-04-17T11:11:46",
"upload_time_iso_8601": "2023-04-17T11:11:46.726601Z",
"url": "https://files.pythonhosted.org/packages/08/0b/a45d615c0320c7451bb5ab3a5874de70c4f87a746263c9c838d18f5be258/telebirr-0.1.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ec3fd53cfd2c83301708bccc842364b4a0216f44ee1fa8b9850c0965f800a9c3",
"md5": "e82af067cde8fa9099ddea8930cc50d6",
"sha256": "d88cbee701dad1f1a9a97c9faa3d24838df39a2752f53cf830abdbec177933db"
},
"downloads": -1,
"filename": "telebirr-0.1.11.tar.gz",
"has_sig": false,
"md5_digest": "e82af067cde8fa9099ddea8930cc50d6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8480,
"upload_time": "2023-04-17T11:11:47",
"upload_time_iso_8601": "2023-04-17T11:11:47.992459Z",
"url": "https://files.pythonhosted.org/packages/ec/3f/d53cfd2c83301708bccc842364b4a0216f44ee1fa8b9850c0965f800a9c3/telebirr-0.1.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-17 11:11:47",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "telebirr"
}
JSON