Package: zotapaysdk
Official Python REST API SDKThis is theofficialpage of theZotapayPython SDK. It is intended to be used by
developers who run modern Python applications and would like to integrate our next generation payments platform.REST API DocsOfficial Deposit DocumentationOfficial Payout DocumentationIntroductionThis Python SDK provides all the necessary methods for integrating the Zotapay Merchant API.
This SDK is to be used by clients, as well as all the related eCommerce plugins for Python applications.The SDK covers all available functionality that ZotaPay's Merchant API exposes.RequirementsA functioning Zotapay Sandbox or Production account and related credentialsPython 3.5 (or higher)InstallationpipinstallzotapaysdkConfigurationAPI CONFIGURATION DOCSCredentials for the SDK can be passed in 3 different ways:To theMGClientitselfThrough environment variablesThrough a configuration fileThis part of the documentation will guide you on how to configure and use this SDK.Before you beginTo use this API, obtain the following credentials from Zotapay:MerchantID	        A merchant unique identifier, used for identification.
MerchantSecretKey	A secret key to keep privately and securely, used for authentication.
EndpointID	        One or more unique endpoint identifiers to use in API requests.ContactZotapayto start your onboarding process and obtain all the credentials.API UrlThere are two environments to use with the Zotapay API:Sandbox environment, used for integration and testing purposes.https://api.zotapay-sandbox.comLive environment.https://api.zotapay.comConfiguration in the codeThe implementation fo the Zotapay API SDK depends on creating an instance of theMGClient. First priority
configuration is the one passed to the client itself.Example:client=zotapaysdk.MGClient(merchant_id=<MerchantIDasreceivedfromZotapay>,merchant_secret_key=<MerchantSecretKeyasreceivedfromZotapay>,endpoint_id=<EndpointIDasreceivedfromZotapay>,request_url=<MGClient.LIVE_API_URLorMGClient.SANDBOX_API_URLor"https://api.zotapay-sandbox.com"...>)Passing configuration to the client itself is best when supporting multiple clients.Environment variables configurationThere are 4 environment variables that need to be set for the API SDK to be configured correctly:ZOTAPAY_MERCHANT_ID             - MerchantID as received from Zotapay
ZOTAPAY_MERCHANT_SECRET_KEY     - MerchantSecretKey as received from Zotapay
ZOTAPAY_ENDPOINT_ID             - EndpointID as received from Zotapay
ZOTAPAY_REQUEST_URL             - https://api.zotapay-sandbox.com or https://api.zotapay.comConfiguration fileConfiguration parameters can be passed through a.mg_envfile placed in the user's home directory.The structure of the files follows Python'sconfigparserExample of a '~/.mg_env' :[MG]
merchant_id=<MerchantID as received from Zotapay>, 
merchant_secret_key=<MerchantSecretKey as received from Zotapay>, 
endpoint_id=<EndpointID as received from Zotapay>, 
request_url=<MGClient.LIVE_API_URL or MGClient.SANDBOX_API_URL or "https://api.zotapay-sandbox.com"...>UsageIn order to use the SDK we need to instantiate a client:fromzotapaysdk.clientimportMGClientmg_client=MGClient()DepositA deposit request can be generated in two different ways:fromzotapaysdk.mg_requestsimportMGDepositRequestexample_deposit_request_with_kwargs=MGDepositRequest(merchant_order_id="QvE8dZshpKhaOmHY",merchant_order_desc="Test order",order_amount="500.00",order_currency="THB",customer_email="customer@email-address.com",customer_first_name="John",customer_last_name="Doe",customer_address="5/5 Moo 5 Thong Nai Pan Noi Beach, Baan Tai, Koh Phangan",customer_country_code="TH",customer_city="Surat Thani",customer_zip_code="84280",customer_phone="+66-77999110",customer_ip="103.106.8.104",redirect_url="https://www.example-merchant.com/payment-return/",callback_url="https://www.example-merchant.com/payment-callback/",custom_param="{\"UserId\":\"e139b447\"}",checkout_url="https://www.example-merchant.com/account/deposit/?uid=e139b447",)or alternativelyexample_deposit_request=MGDepositRequest().\set_merchant_order_id("QvE8dZshpKhaOmHY").\set_merchant_order_desc("Test order").\set_order_amount("500").\set_order_currency("USD").\set_customer_email("test@test.com").\set_customer_first_name("John").\set_customer_last_name("Doe").\set_customer_address("5/5 Moo 5 Thong Nai Pan Noi Beach, Baan Tai, Koh Phangan").\set_customer_country_code("TH").\set_customer_city("Surat Thani").\set_customer_zip_code("84280").\set_customer_phone("+66-66006600").\set_customer_ip("103.106.8.104").\set_redirect_url("https://www.example-merchant.com/payment-return/").\set_callback_url("https://www.example-merchant.com/payment-callback/").\set_custom_param("{\"UserId\":\"e139b447\"}").\set_checkout_url("https://www.example-merchant.com/account/deposit/?uid=e139b447")Sending the request to Zotapay happens through the client:deposit_response=mg_client.send_deposit_request(example_deposit_request)print("Deposit Request is "+str(deposit_response.is_ok))In order to send aCredit Card Depositwe need to append the appropriateCredit Card Paramswhich is achieved through sending aMGCardDepositRequestexample_cc_deposit_request=MGCardDepositRequest(merchant_order_id="QvE8dZshpKhaOmHY",merchant_order_desc="Test order",order_amount="500.00",order_currency="THB",customer_email="customer@email-address.com",customer_first_name="John",customer_last_name="Doe",customer_address="5/5 Moo 5 Thong Nai Pan Noi Beach, Baan Tai, Koh Phangan",customer_country_code="TH",customer_city="Surat Thani",customer_zip_code="84280",customer_phone="+66-77999110",customer_ip="103.106.8.104",redirect_url="https://www.example-merchant.com/payment-return/",callback_url="https://www.example-merchant.com/payment-callback/",custom_param="{\"UserId\":\"e139b447\"}",checkout_url="https://www.example-merchant.com/account/deposit/?uid=e139b447",# CC PARAMS HEREcard_number="3453789023457890",card_holder_name="John Doe",card_expiration_month="08",card_expiration_year="2027",card_cvv="123")deposit_response=mg_client.send_deposit_request(example_cc_deposit_request)print("Deposit Request is "+str(deposit_response.is_ok))Working withDeposit ResponseEach deposit attempt against a Zotapay returns either aMGDepositResponseorMGCardDepositResponse.The above objects are simply a wrapper around the standard HTTP response as describedhere.The response classes contain an additional helper method that validates the signature of the response when provided with amerchant_secret_keyPayoutSending a payout request is almost identical to sending a deposit request.The request is built:fromzotapaysdk.mg_requestsimportMGPayoutRequestexample_payout_request=\MGPayoutRequest(merchant_order_id="TbbQzewLWwDW6goc",merchant_order_desc="Test order",order_amount="500.00",order_currency="MYR",customer_email="customer@email-address.com",customer_first_name="John",customer_last_name="Doe",customer_phone="+66-77999110",customer_ip="103.106.8.104",callback_url="https://www.example-merchant.com/payout-callback/",customer_bank_code="BBL",customer_bank_account_number="100200",customer_bank_account_name="John Doe",customer_bank_branch="Bank Branch",customer_bank_address="Thong Nai Pan Noi Beach, Baan Tai, Koh Phangan",customer_bank_zip_code="84280",customer_bank_province="Bank Province",customer_bank_area="Bank Area / City",customer_bank_routing_number="000",custom_param="{\"UserId\":\"e139b447\"}",checkout_url="https://www.example-merchant.com/account/withdrawal/?uid=e139b447")The client returnsMGPayoutResponsewhich is again a wrapper around the standard HTTP response.CallbacksMGCallbackis a class that parses the raw HTTP Request sent from Zotapay to the configured endpoint. It's purpose
is to make working with callbacks manageable.ValidationsTheMGRequestclass implements avalidate()method which can be used for parameter validation of the request
offline before the request is being sent. It's purpose is to check whether all the values passsed to the different
parameters is in-line with what Zotapay's endpoint expects. See the API DOCS for more info and guidance about the
format of the different parameters.Test Coverage