Invoice creation

This documentation page describes the process of creating an invoice in Polus Payments using the HTTP API. By following the steps outlined in this guide, you can create an invoice and initiate a payment transaction through our platform. Whether you're a developer building a custom integration or a business owner looking to streamline your payment processes, this documentation provides a comprehensive overview of the API endpoints and parameters necessary to create successful invoice payments in Polus Payments.

API endpoint

Below is the official HTTP API endpoint for Polus Payments that you can use to integrate our payment platform into your application or website. TLS usage is mandatory.

https://api.poluspay.com/

Authorization

Authorization is a crucial step in using the Polus Payments API to securely interaction. To get started, merchants must register and create an account at app.poluspay.com, where they will be provided with a unique merchant ID in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, as well as an API Key. To authorize API requests, merchants must generate a signature by applying HMAC SHA512 to the HTTP body, using their API Key as the key. This signature must be included in the x-signature header of each API request. Additionally, merchants must include their unique merchant ID in the x-merchant-id header to ensure that their requests are processed correctly.

golangpythonjavaphp

package main

import (
	"crypto/hmac"
	"crypto/sha512"
	"encoding/hex"
	"fmt"
)

func main() {
	apiKey := []byte("b153...da1c")
	body := []byte(`{"some":"data"}`)

	h := hmac.New(sha512.New, apiKey)
	h.Write(body)

	sign := h.Sum(nil)
	fmt.Printf("x-signature: %s\n", hex.EncodeToString(sign))
}

python

import json
import hmac
import hashlib

def main():
    api_key = bytes("b153...da1c", 'utf-8')
    body = {"some": "data"}

    body_bytes = bytes(json.dumps(body, separators=(',', ':')), 'utf-8')
    sign = hmac.new(api_key, body_bytes, hashlib.sha512)

    print(f"x-signature: {sign.hexdigest()}")

if __name__ == "__main__":
    main()

java

import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public class Main {
    public static String hex(byte[] bytes) {
        StringBuilder result = new StringBuilder();
        for (byte aByte : bytes) {
            result.append(String.format("%02x", aByte));
        }

        return result.toString();
    }

    public static void main(String[] args) throws NoSuchAlgorithmException, InvalidKeyException {
        byte[] apiKey = "b153...da1c".getBytes();
        byte[] body = "{\"some\":\"data\"}".getBytes();

        Mac hmacSha512 = Mac.getInstance("HmacSHA512");
        SecretKeySpec keySpec = new SecretKeySpec(apiKey, "HmacSHA512");
        hmacSha512.init(keySpec);
        byte[] sign = hmacSha512.doFinal(body);

        System.out.printf("x-signature: %s\n", hex(sign));
    }
}

php

<?php

$apiKey = "b153...da1c";
$body = '{"some":"data"}';

$sign = hash_hmac('sha512', $body, $apiKey, true);
$signature = bin2hex($sign);

echo "x-signature: $signature\n";

Possible types

PaymentAssetRequest

field	type	desc
`amount`	`decimal`	amount in human readable format, like: 100.00
`address`	`string`	destination wallet address

CreatePaymentRequest

field	type	desc
`description`	`string`	invoice description will be shown to merchant customer
`assets`	`map[network][assetName]PaymentAssetRequest`	list of assets which merchant wants to receive

Possible values of network and assetName – you can get on POST /public/payment.assets.get

PaymentAsset

field	type	desc
`network`	`string`	selected network
`name`	`string`	selected asset name
`amount`	`decimal`	amount in the minimum unit of asset. e.g: 10200000
`amount_decimals`	`decimal`	human readable amount. e.g: 10.2
`fee`	`decimal`	fee in the minimum unit of asset
`address`	`string`	destination wallet address

PaymentTransaction

field	type	desc
`hash`	`string`	transaction hash in blockchain
`network`	`string`	network name, Example: polygon
`network_id`	`int`	network id, Example: 137
`notification_delivered`	`bool`	flag that indicates whether a webhook has been delivered

Payment

field	type	desc
`id`	`uuid`	unique identifier of that payment
`merchant_id`	`uuid`	identifier of your merchant
`description`	`string`	invoice description passed in `CreatePaymentRequest`
`assets`	`[]PaymentAsset`	list of assets which merchant wants to receive
`evm_fee_address`	`string`	service fee address
`status`	`string`	payment status
`paid_asset`	`PaymentAsset\|null`	one of asset from assets list which was received by merchant. Not null when payment is success
`transaction`	`PaymentTransaction\|null`	that value will be filled after payment completion
`expires_at`	`date`	date of payment expiration in UTC
`created_at`	`date`	date of payment creation in UTC

Possible values of status – | "pending" | "in_progress" | "success" | "failed" CreateLitePaymentRequest

field	type	desc
`merchant_id`	`uuid`	your merchant id
`description`	`string`	invoice description will be shown to merchant customer
`target_asset`	`string`	asset which you want to receive
`amount`	`decimal`	amount in human readable format, like: 100.00
`order_id`	`string\|null`	order id in your system, can be null or empty
`signature`	`string`	hmac_sha512('description\|target_asset\|amount\|order_id', merchant.signing_key) encoded in hex
`auto_redirect`	`bool`	default: `false`. Set this option to `true` if you want to redirect user to `pay_link`

Possible values of target_asset – you can get on POST /public/payment.assets.get

Payment creation with using presaved addresses in merchant dashboard

Important: Before using this method, you need add wallets in Dashboard > Merchants > Select your merchant > Tokens & Addresses

`POST` `/lite/payment.create`

That method returns Payment

example request

json

{
    "merchant_id": "8a349ce2-97a5-43d4-a65d-c8dcde946bd5",
    "description": "Test lite payment",
    "target_asset": "usdt",
    "amount": "10",
    "order_id": "asdasd1231",
    "signature": "86fa1a833e5d161a345f5c6d8d30c5889de1cc1386f268a55183f7e16ffd27508528591eb0ce465fcd79812ba269d988874c60ac2b18a469e125acaea0930167",
    "auto_redirect": false
}

example response

json

{
    "id": "4f18c147-da95-4454-882d-e154fd7ad8ee",
    "merchant_id": "8a349ce2-97a5-43d4-a65d-c8dcde946bd5",
    "description": "Telegram Premium",
    "pay_link": "https://form.poluspay.com/id/4f18c147-da95-4454-882d-e154fd7ad8ee",
    "order_id": "asdasd1231",
    "assets": [
        {
            "network": "polygon",
            "name": "usdt",
            "amount": "9950000",
            "amount_decimals": "9.95",
            "fee": "50000",
            "fee_decimals": "0.05",
            "address": "0x8C8D7C46219D9205f056f28fee5950aD564d7464"
        },
        {
            "network": "ethereum",
            "name": "usdt",
            "amount": "9950000",
            "amount_decimals": "9.95",
            "fee": "50000",
            "fee_decimals": "0.05",
            "address": "0x8C8D7C46219D9205f056f28fee5950aD564d7464"
        },
        {
            "network": "bsc",
            "name": "usdt",
            "amount": "9950000000000000000",
            "amount_decimals": "9.95",
            "fee": "50000000000000000",
            "fee_decimals": "0.05",
            "address": "0x8C8D7C46219D9205f056f28fee5950aD564d7464"
        }
    ],
    "paid_asset": null,
    "evm_fee_address": "0x71ca3dd1041c73d2445b48149eb982523ac7d4a5",
    "status": "pending",
    "transaction": null,
    "expires_at": "2023-06-08T14:47:50.317802Z",
    "created_at": "2023-06-08T13:47:50.31884Z"
}

Payment creation with passing addresses

`POST` `/merchant/payment.create`

example request

json

{
    "description": "Telegram Premium",
    "assets": {
        "litecoin": {
            "ltc": {
                "amount": "10",
                "address": "MLJhWniUivYwtou2RKfrLbwjxxyqGoibTY"
            }
        },
        "bitcoin": {
            "btc": {
                "amount": "10",
                "address": "bc1qx2x5cqhymfcnjtg902ky6u5t5htmt7fvqztdsm028hkrvxcl4t2sjtpd9l"
            }
        }
    }
}

example response

json

{
    "id": "4f18c147-da95-4454-882d-e154fd7ad8ee",
    "merchant_id": "8a349ce2-97a5-43d4-a65d-c8dcde946bd5",
    "description": "Telegram Premium",
    "pay_link": "https://form.poluspay.com/id/4f18c147-da95-4454-882d-e154fd7ad8ee",
    "assets": [
        {
            "network": "polygon",
            "name": "usdt",
            "amount": "9950000",
            "amount_decimals": "9.95",
            "fee": "50000",
            "fee_decimals": "0.05",
            "address": "0x8C8D7C46219D9205f056f28fee5950aD564d7464"
        },
        {
            "network": "ethereum",
            "name": "usdt",
            "amount": "9950000",
            "amount_decimals": "9.95",
            "fee": "50000",
            "fee_decimals": "0.05",
            "address": "0x8C8D7C46219D9205f056f28fee5950aD564d7464"
        },
        {
            "network": "bsc",
            "name": "usdt",
            "amount": "9950000000000000000",
            "amount_decimals": "9.95",
            "fee": "50000000000000000",
            "fee_decimals": "0.05",
            "address": "0x8C8D7C46219D9205f056f28fee5950aD564d7464"
        }
    ],
    "paid_asset": null,
    "evm_fee_address": "0x71ca3dd1041c73d2445b48149eb982523ac7d4a5",
    "status": "pending",
    "transaction": null,
    "expires_at": "2023-06-08T14:47:50.317802Z",
    "created_at": "2023-06-08T13:47:50.31884Z"
}

TIP

All fields containing time use ISO 8601 standart.

Invoice creation ​

API endpoint ​

Authorization ​

Payment creation with using presaved addresses in merchant dashboard ​

POST /lite/payment.create ​

Payment creation with passing addresses ​

POST /merchant/payment.create ​

Invoice creation

API endpoint

Authorization

Payment creation with using presaved addresses in merchant dashboard

`POST` `/lite/payment.create`

Payment creation with passing addresses

`POST` `/merchant/payment.create`