SDK for Python

SDK for Python is a software development kit for development of web services which are capable of integrating with the ECommPay payment solutions to perform purchase by using Payment Page. This section describes how to use SDK for Python to build purchase experience from inside of your web service.

SDK for Python is compatible with Python version 3.5 or higher. You can download SDK for Python from GitHub or PyPI:

What can I do with SDK for Python?

SDK for Python allows you to do the following:
  • Calculate signature and generate request for opening the Payment Page payment form
  • Check callback signature and extract payment details from callbacks

What's inside?

SDK for Python contains the libraries for development and automated testing, as well as the service files.

Using SDK for Python

To start using SDK for Python you need to complete the following tasks:

  1. Make sure you have you have ready your merchant ID and secret key obtained from ECommPay:
    1. If your company has never obtained any ID or secret key from ECommPay, you need to submit an application for connecting to the ECommPay payment platform at https://ecommpay.com/apply-now/.
    2. If your company already has an ID and a secret key to sign messages obtained from ECommPay, you need to notify ECommPay customer support that you want to use SDK for Python and consult with the customer support on how to arrange a test run.
  2. Integrate the ECommPay payment solution in your web service:
    1. Install the SDK for Python libraries.
    2. Import the libraries you need into your web service application.
  3. Test and put your web service in production mode.
    • Use test merchant ID and test values for payment parameters from the tests library.
    • Once testing is complete, request your production merchant ID from ECommPay and put your web service in production mode.

With any questions regarding usage of SDK for Python contact ECommPay technical support service at support@ecommpay.com.

Installing and importing libraries

You can install the SDK for Python libraries manually or automatically with pip, a package-management system used to install and manage software packages written in Python.

The following steps describe how to install the SDK for Python libraries by using pip:

  1. If you have not yet installed pip, you need to download, install and check settings. For more information, see https://pip.pypa.io/en/stable/.
  2. Navigate into the web service directory in command line interface and run the following command:
    pip install ecommpay-sdk

    Pip automatically downloads the SDK for Python libraries in the Scripts directory to enable you to use all the classes provided by the libraries.

  3. Import the classes into your web service project:
    from payment_page_sdk.gate import Gate
    from payment_page_sdk.payment import Payment

Opening payment form

Payment form invocation request consists of a set of parameters, which are signed to secure the data transmitted to the ECommPay payment platform. SDK for Python allows you to seamlessly sign parameters and generate requests. To open the Payment Page payment form by using SDK for Python do the following:

  1. Create an instance of the Payment class and specify payment details.
    payment = Payment('186', 'ECT_TEST_1555943554067')
        // Project ID and payment ID and payment ID must be unique within your project scope
    payment.payment_amount = 1001
        // Amount in minor currency units
    payment.payment_currency = 'EUR'
        //  Currency in ISO-4217 alpha-3 format
    payment.payment_description = 'Test payment'
        // Payment description (optional)

    All the parameters in this example are required to perform any payment. You can also use any optional parameters available for Payment Page. For more information about the Payment Page invocation parameters, see Payment Page invocation parameters.

  2. Create a gate instance and initiate it with the secret key you obtained from the ECommPay support service. The secret key is required to sign invocation requests.
    gate = Gate('<secret_key>')
        // Secret key you obtained from technical support service
  3. Generate payment form invocation request:

    payment_url = gate.get_purchase_payment_page_url(payment)

    Correct payment form invocation request contains payment parameters and signature (abbreviated):

    https://paymentpage.ecommpay.com/payment?signature=OEKRlLXQsa2..
                   ..gWg%3D%3D&payment_id=pid_1555943554067...
  4. Use the request in your web service code to open the payment form.

Here is an example of generating a URL for opening an English payment form. The payment method selection page includes detailed payment information including amount, currency and short payment description.

Figure: Example of generating Payment Page invocation request

payment = Payment('186', 'ECT_TEST_1555943554067')
    // Project ID and payment ID and payment ID must be unique within your project scope
payment.payment_currency = 'EUR'  
    // Amount in minor currency units and currency in ISO-4217 alpha-3 format
payment.payment_description = 'Test payment'
    // Payment description
payment.language_code = 'en'
    // Language code to use in payment form
gate = Gate('<secret_key>')    
    // Secret key
payment_url = gate.get_purchase_payment_page_url(payment)
    // Complete request with signature

Processing callbacks

The ECommPay payment platform sends payment results to the callback URL you specified when connecting to ECommPay. Callback is an HTTP POST request that contains response data in JSON format. To extract payment information from the JSON string do the following:

  1. Create an instance of Gate with the secret key, if you did not it earlier.
    gate = Gate('<secret_key>')
  2. Create an instance of Callback by using the JSON string from the callback obtained from the ECommPay payment platform:

    callback = gate.handle_callback(data)
  3. Use the following methods for extracting callback information. You can get either full payment information or request specific payment parameters:

    callback.get_payment_id()            // Getting payment ID
    callback.get_payment_status()        // Getting payment status
    callback.get_payment()               // Getting payment body

By using SDK for Python, you can automatically check validity of callback signature. Below, you will find an example of callback that includes signature and payment results.

Figure: Sample payment callback

{
             "project_id": 186,       // Project ID
             "payment": {             // Payment details
             "id": "pid_1555943554067",       // Payment ID
             "type": "purchase",  // Payment type
             "status": "success", // Payment status
             "date": "2018-08-28T09:11:28+0000",  // Payment date and time
             "method": "card",  // Payment method
             "sum": {           // Payment amount and currency
             "amount": 1000,
             "currency": "EUR"
             },
             "description": "Test payment"  // Payment description
             },
             "account": {           // Payment instrument details
             "number": "431422******0056",
             "token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2",
             "type": "visa",
             "card_holder": "ADA LOVELACE",
             "id": 778804,
             "expiry_month": "11",
             "expiry_year": "2021"
             },
             "operation": {     // The last operation within payment
             "id": 17839000001150,  // Operation ID
             "type": "sale",        // Operation type
             "status": "success",   // Operation status
             "date": "2018-08-28T09:11:28+0000", // Operation date and time
             "created_date": "2018-08-28T09:10:50+0000",
             "request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Request ID
             "sum_initial": {    // Initial payment amount and currency 
             "amount": 1000,
             "currency": "EUR"
             },
             "sum_converted": {
             // Payment amount and currency as per applicable project conversion rules
             "amount": 1000,
             "currency": "EUR"
             },
             "provider": {     // Payment details in payment system
             "id": 6,
             "payment_id": "15354474886323",
             "date": "2018-02-07T08:34:24+0000",
             "auth_code": "563253",
             "endpoint_id": 6
             },
             "code": "0",          // Unified response code
             "message": "Success", // User-readable response code
             "eci": "05"           // ECI code, result of 3-D Secure check
              },
              "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..."  // Signature
              }

Related links