SDK for Go

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

SDK for Go is compatible with Go version 1.8 or later. You can download SDK for Go from Git: https://github.com/ITECOMMPAY/paymentpage-sdk-go.

What can I do with SDK for Go?

SDK for Go allows you to do the following:

Calculate signature and generate request for opening the Payment Page payment form.
Check callback signatures and extract payment details from callbacks.

What's inside?

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

Using SDK for Go

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

Make sure 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 at https://ecommpay.com/apply-now/ for connecting to the ecommpay payment platform.
2. If your company already has an ID and a secret key to sign messages obtained from ecommpay, you need to notify the ecommpay technical support specialists that you want to use SDK for Go and consult the customer support on how to arrange a test run.
Integrate the ecommpay payment solution in your web service:
1. Install the SDK for Go libraries into a directory inside your web service project.
2. Import the libraries you need into your web service application.
Test and put your web service in production mode.
1. Request test card numbers and test project ID from ecommpay, debug and test your web service.
2. Once testing is complete, request your production project ID from ecommpay and put your web service in production mode.

With any questions regarding the use of SDK for Go, contact the ecommpay technical support specialists at support@ecommpay.com.

Installing and importing libraries

You can install the SDK for Go libraries manually or by using automated procedures supported by the development environment you use.

The following steps describe how to manually install the SDK for Go libraries.

If no $GOPATH environment variable is set, you need to set one. The $GOPATH is used to specify directories outside of $GOROOT that contains the source for Go projects and their binaries.
Run the following command in the command line of your operating system:
```
go get github.com/ITECOMMPAY/paymentpage-sdk-go
```
The command downloads the SDK for Go libraries in the $GOPATH directory to enable you to use all the classes provided by the libraries.
Import the SDK for Go into your web service source code in import section by running the following command:
```
import "github.com/ITECOMMPAY/paymentpage-sdk-go"
```

Opening payment form

Warning: Starting August 12, 2024, Visa Rules will be updated to expand the set of parameters mandatory for processing Visa card payments with the 3‑D Secure authentication. In such cases it will be required to specify the customer's phone number or email. At least one of these parameters must be specified when creating an instance of payment.

However, it is also recommended that these and a number of other parameters (with the billing address information) are specified for payments made with cards of other card schemes. According to Visa, rigorous use of these parameters can significantly increase payment acceptance rates (up to 6 %) and drastically decrease the number of operations flagged as fraudulent after they have been processed (up to 65 %).

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 Go allows you to seamlessly sign parameters and generate requests. To open the Payment Page payment form by using SDK for Go do the following:

Create an instance of the payment class and specify payment details.

payment := paymentpage.NewPayment(186, "TEST_1555943554067")
          // Project ID and payment ID, must be unique within your project scope
payment.SetParam(paymentpage.ParamPaymentCurrency, "EUR")
          // Currency in the ISO-4217 alpha-3 format
payment.SetParam(paymentpage.ParamPaymentAmount, 1000)
          // Amount in minor currency units
payment.SetParam(paymentpage.ParamPaymentDescription, "Test payment")
          // Payment description (optional)

All parameters in this example, except for the payment description, are mandatory for any purchase. You may also need to pass other parameters, for example, the customer's email or phone number when the 3‑D Secure authentication is required. Such parameters must be specified as follows.

payment.SetParam(paymentpage.ParamCustomerPhone, "The customer's phone number. Must have from 4 to 24 digits")
payment.SetParam(paymentpage.ParamCustomerEmail, "The customer's email")

In addition, for card purchases you are recommended to pass the customer's billing address information: the country code in ISO 3166-1 alpha-2 (details), the postal code, the city, and the street address. Such parameters are specified as follows.

payment.SetParam(paymentpage.ParamBillingPostal, "The postal code of the customer's billing address")
payment.SetParam(paymentpage.ParamBillingCountry, "The country of the customer's billing address, in ISO 3166-1 alpha-2")
payment.SetParam(paymentpage.ParamBillingCity, "The city of the customer's billing address")
payment.SetParam(paymentpage.ParamBillingAddress, "The street of the customer's billing address")

You can also use any other optional parameters available for Payment Page. For more information about the Payment Page invocation parameters, see Parameters for opening payment form.

Create a gate instance and initiate it with the secret key you obtained from the ecommpay technical support specialists. The secret key is required to sign invocation requests.
```
gate := paymentpage.NewGate("<secret_key>")
   // Secret key you obtained from the technical support service
```

Generate payment form invocation request:

paymentPageUrl := gate.GetPaymentPageUrl(*payment)

Payment form invocation request must contain payment parameters and signature (abbreviated):

https://paymentpage.ecommpay.com/payment?signature=OEKRlLXQsa2..
               ..gWg%3D%3D&payment_id=pid_1555943554067...

Use the generated request to open the payment form, for example:

<link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" />
<script type="text/javascript" src="https://paymentpage.ecommpay.com/shared/merchant.js"></script>
<script type="text/javascript">
    EPayWidget.run({ baseUrl: '<the URL generated in the previous step>'}, 'get');
</script>

Other ways to open the payment form are described in the following article.

Here is an example of generating a URL for opening a payment form in English. 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 := paymentpage.NewPayment(186, "test_payment_id")
    // Project ID and payment ID, must be unique within your project scope
payment.SetParam(paymentpage.ParamPaymentAmount, 1000)
    // Amount in minor currency units
payment.SetParam(paymentpage.ParamPaymentCurrency, "EUR")
    // Currency in the ISO-4217 alpha-3 format
payment.SetParam(paymentpage.ParamPaymentDescription, "Test payment")
    // Payment description (optional)
payment.SetParam(paymentpage.ParamLanguageCode, "en")
    // Language code to use in payment form
gate := paymentpage.NewGate("<secret_key")
    // Secret key
paymentPageUrl := gate.GetPaymentPageUrl(*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 response JSON string, do the following:

Create an instance of gate and initiate it with the secret key if you did not do it earlier:
```
gate := paymentpage.NewGate("<secret_key>")
```
Create an instance of callback by using the JSON string from the callback obtained from the ecommpay payment platform:
```
callback, err := gate.HandleCallback(data)
```
If signature is incorrect or extracting payment details from callback results in errors, an error instance is returned.
Use the following methods for extracting callback information. You can get either full payment information or request specific payment parameters:
```
callback.GetPaymentId()             // Getting payment ID
callback.GetPaymentStatus()         // Getting payment status
callback.GetPayment()               // Getting payment body
```
By using SDK for Go, you can automatically check validity of the callback signature. Below, you can find an example of a callback that includes a 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": "2021-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": "2024"
             },
             "operation": {     // The last operation within payment
             "id": 17839000001150,  // Operation ID
             "type": "sale",        // Operation type
             "status": "success",   // Operation status
             "date": "2021-08-28T09:11:28+0000", // Operation date and time
             "created_date": "2021-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": "2021-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
              }