MENU navbar-image

Introduction

Welcome to UtopiaPay docs

This documentation aims to provide all the information you need to use and implement our gateway to your apps.

Using the service

In order to use our service you must have an account registred and at least 1 site inside or outside Utopia ecosystem

You can manually add the gateway to your following this guide, or if you use WordPress, you can download one of our plugins for WooCommerce or Easy Digital Downloads

How to add UtopiaPay to your website

First of all you must create an account and check the data from this page, here you can find your data in order to use the service.


First create an json containing the following data:


Next use sodium to crypt the data with the base64 encoded secret key The crypted data must contain inside the data variable as a base64 string that contains the string json, the id as int and the nonce that will be used to add a layer of security and check the transaction

Create an object that contains:


Finally send the json object encrypted in base64 to our gateway and the payment will start

Preparing data

Example file that crypt the data and returns the required data 

    

    try{

        $token = "YOUR-TOKEN";
        $id='YOUR-ID';
        $secretKey = "YOUR-SECRET-KEY";
        // Destination page after the patment is successsfull

        // Use http:// if you are in utopia and https:// in clearnet
        $webTo = "http://destinationpage.com";  

        // generate random orderID containing random numbers and random characters
        $orderID = substr(md5(rand()), 0, 7);

        // Currency that you want to convert to crp: Ex 1 USD = 0.9 CRP
        $currency = "CRP";

        //create the data array
        $data = array(
            "amount" => $_POST['amount'], 
            "orderID" => $orderID,
            "token" => $token,
            "webTo" => $webTo,
            "id" => $id,
            "currency" => $currency,
        );
        //create the json string object
        $dataToCrypt = json_encode($data);

        //generate the nonce
        $nonce = random_bytes(SODIUM_CRYPTO_BOX_NONCEBYTES);

        // encrypt the data
        $encryptedText = sodium_crypto_box($dataToCrypt, $nonce, base64_decode($secretKey));

        // code it in base64
        $dataCrypted = base64_encode($encryptedText);
        $nonce = base64_encode($nonce);

    }catch(Exception $e){
        echo $e->getMessage();
    }

    // return the base64 json encoded object with the data encrypted, nonce and id
    echo base64_encode( json_encode([
        "id"=>$id,
        "data"=>$dataCrypted,
        "nonce"=>$nonce,
    ]));



    

/// this packages must be instaled
/// go get github.com/pkg/errors
/// go get golang.org/x/crypto/nacl/box

package main

import (
    "crypto/rand"
    "encoding/base64"
    "encoding/json"
    "fmt"
    "github.com/pkg/errors"
    "golang.org/x/crypto/nacl/box"
    "net/http"
)

func main() {
    token := "YOUR-TOKEN"
    id := "YOUR-ID"
    secretKey := "YOUR-SECRET-KEY"
    // Destination page after the patment is successsfull
    // Use http:// if you are in utopia and https:// in clearnet
    webTo := "http://destinationpage.com"

    // generate random orderID containing random numbers and random characters
    orderID := RandomString(7)

    // Currency that you want to convert to crp: Ex 1 USD = 0.9 CRP
    currency := "CRP"

    // create the data map
    data := map[string]interface{}{
        "amount":  0, // replace with the actual amount value
        "orderID": orderID,
        "token":   token,
        "webTo":   webTo,
        "id":      id,
        "currency": currency,
    }

    // encode the data as JSON string
    dataToCrypt, err := json.Marshal(data)
    if err != nil {
        fmt.Println(errors.Wrap(err, "failed to marshal data"))
        return
    }

    // generate the nonce
    nonce := make([]byte, box.NonceSize)
    if _, err := rand.Read(nonce); err != nil {
        fmt.Println(errors.Wrap(err, "failed to generate nonce"))
        return
    }

    // encrypt the data
    publicKey, err := base64.StdEncoding.DecodeString(secretKey)
    if err != nil {
        fmt.Println(errors.Wrap(err, "failed to decode secret key"))
        return
    }
    var publicKeyBytes [32]byte
    copy(publicKeyBytes[:], publicKey)
    encryptedText := box.Seal(nil, dataToCrypt, &nonce, &publicKeyBytes)

    // encode the encrypted data and nonce as base64
    dataCrypted := base64.StdEncoding.EncodeToString(encryptedText)
    nonceEncoded := base64.StdEncoding.EncodeToString(nonce)

    // encode the result as JSON string and then as base64
    result := map[string]interface{}{
        "id":   id,
        "data": dataCrypted,
        "nonce": nonceEncoded,
    }
    resultJSON, err := json.Marshal(result)
    if err != nil {
        fmt.Println(errors.Wrap(err, "failed to marshal result"))
        return
    }
    resultBase64 := base64.StdEncoding.EncodeToString(resultJSON)

    // print the result
    fmt.Println(resultBase64)
}

// RandomString generates a random string with the given length
func RandomString(length int) string {
    const chars = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
    b := make([]byte, length)
    for i := range b {
        b[i] = chars[rand.Intn(len(chars))]
    }
    return string(b)
}

Data file

Data Fields

Amount  string  

Amount in the selected currency that user must pay

OrderID   string  

String required for you to identify the order and display in the gateway.

Token  string  

Token used to authenticate you and confirm the inegrity of the transaction.

webTo  string  

Website where user will be redirected to after the payment. Example: http://www.example.com

id  integer  

Unique ID displayed in sites page.

currency  string  

Currency to convert to CRP.

Data returned-PHP

What must the php file returns

Json_Object  string  

An base64 string with a json string that contains:
{ "id"=>$id, "data"=>$dataCrypted, "nonce"=>$nonce, }

JS: Example requesting the crypted data from the payment.php file


function startPayment(amount, orderId) {

    var param = {
        "amount": amount,
        "orderId": orderId
    };

    $.ajax({
        data: param,
        url: '/payment/main.php',
        type: 'post',
        beforeSend: function () { },
        success: function (response) {
            var form = document.createElement('form');
            document.body.appendChild(form);
            form.method = 'post'; form.action = "http://utopiapay.io/checkout/pre/";
            var dataRecived = document.createElement('input');
            dataRecived.type = 'hidden';
            dataRecived.name = "data";
            dataRecived.id = "data";
            dataRecived.value = response;
            form.appendChild(dataRecived);
            form.submit();
        },
        error: function (response) {
            console.log(response);
        }
    });
}

Request-JS   

POST checkout/pre

Data-JS

Data that must be sent to server

data   string  

String received from the script containing an json object with the base64 encoded data and the id mentioned before


WordPress

If you are using WordPress feel free to download our plugin to add Crypton (CRP) payments to your site

Plugin for WooCommerce

How to add UtopiaPay payment gateway to your WordPress WooCommerce store:

  1. Download the plugin from the download link given below.
  2. Upload the plugin from Plugins -> Add New -> Upload Plugin
  3. Activate the plugin.
  4. Go to WooCommerce -> Settings -> Payments -> UtopiaPay Manage
  5. Enable the plugin and add your UtopiaPay ID, UtopiaPay Token and UtopiaPay Secret Key there and click on save changes button.

Plugin for Easy Digital Downloads

How to add UtopiaPay payment gateway to your WordPress Easy Digital Downloads store:

  1. Download the plugin from the download link given below.
  2. Upload the plugin from Plugins -> Add New -> Upload Plugin
  3. Activate the plugin.
  4. Go to WooCommerce -> Settings -> Payments -> UtopiaPay
  5. Add your UtopiaPay ID, UtopiaPay Token and UtopiaPay Secret Key there and click on save changes button.
  6. Go to Downloads -> Settings -> Payments -> Gateways
  7. Enable "UtopiaPay" in Payment Gateways option. You can checkmark UtopiaPay logo and click on save changes button.

Api

GET api/getTransactions

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'http://utopiapay/api/getTransactions',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ],
        'json' => [
            'user' => 'BNDSAINDBAS798NB9UAS',
            'id' => 74023743,
            'token' => 'NIJAS3289HD9ASDSDA',
            'lim' => 20,
            'site' => 'Optional',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
import (
    "bytes"
    "crypto/rand"
    "encoding/base64"
    "encoding/json"
    "fmt"
    "net/http"
)

func makeRequest() {
    // Set up HTTP client
    client := &http.Client{}

    // Set up endpoint URL and request method
    url := "http://utopiapay/api/getTransactions"
    method := "get"

    // Set up headers
    headers := make(http.Header)
    headers = [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ]

    // Set up query parameters
    queryParams := make(map[string]string)

    // Set up request body
    var requestBody []byte
    // Set up application/x-www-form-urlencoded or application/json request body
    requestBodyBytes, err := json.Marshal([
            'user' => 'BNDSAINDBAS798NB9UAS',
            'id' => 74023743,
            'token' => 'NIJAS3289HD9ASDSDA',
            'lim' => 20,
            'site' => 'Optional',
        ])
    if err != nil {
        panic(err)
    }
    requestBody = bytes.NewBuffer(requestBodyBytes)

    // Create HTTP request
    req, err := http.NewRequest(method, url, requestBody)
    if err != nil {
        panic(err)
    }

    // Set headers
    req.Header = headers

    // Set query parameters
    query := req.URL.Query()
    for k, v := range queryParams {
        query.Add(k, v)
    }
    req.URL.RawQuery = query.Encode()

    // Send HTTP request and get response
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }

    // Print response body
    defer resp.Body.Close()
    responseBody, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }
    fmt.Println(string(responseBody))
}

Example response (200):


{
  "code": "success",
  "result": [
      {
          "id": 25,
          "orderID": "3301",
          "paymentID": "Kyn899pt7GLqXkjv5r4f0PIm",
          "website": "utopiapay.io",
          "approved": 1,
          "amount": 0.01,
          "currency": "CRP",
          "time": "2022-01-23 10:55:13"
      },
      {
          "id": 24,
          "orderID": "3301",
          "paymentID": "YhZdY9VzK2se8eWZSsnqM135",
          "website": "utopiapay.io",
          "approved": 0,
          "amount": 21,
          "currency": "CRP",
          "time": "2022-01-23 10:33:55"
      },
      {
          "id": 23,
          "orderID": "3301",
          "paymentID": "Jl4lq0TG1sW9hbjjt60ApK13",
          "website": "utopiapay.io",
          "approved": 1,
          "amount": 21,
          "currency": "uUSD",
          "time": "2022-01-23 10:33:53"
      }
  ]

Request   

GET api/getTransactions

Body Parameters

user  string  

Your public key

id  integer  

The id located in website dashboard page.

token  string  

Token required to auth you.

lim  integer optional  

Data to get. (Default 20, max 200).

site  string optional  

Get data from a specific site. Default all.

Response

Response Fields

code    

String If the request is a success or an error

result    

The array of the transactions

id  integer  

The numerated id of the transaction

paymentID  string  

The transaction id generated by us

orderID  string  

Your order id generated

website  string  

The site where the transaction was made

approved  integer  

Can be completed (1), or not completed (0)

amount  integer  

The amount of the transaction in the specific currency

currency  string  

The currency used to pay

time  string  

When the transaction was made