Payment gateway
MVP
Liberland payment gateway is unique in that it handles most of the data on chain and does not keep permanent records on the server itself, both for legal and decentralization reasons. It is merely a middleman telling the buyer how to pay the merchant, and then notifying the merchant of the payment.
The merchant will build a link similar to this
http://testnet.liberland.org/home/wallet/gateway/557?price=4&toId=5Cz12KQKCmLMg7GULaJfAEe78DtTHSfs7LjaJKtWSA1DtwQg&callback=https%3A%2F%2Fgoogle.com&remark=%27Get%20citizenship%20now%27&failure=https%3A%2F%2Fseznam.cz&hook=https%3A%2F%2Fwebhook.site%2F06892882-f63f-4bfb-a57d-632d2953e631
The first number is the order id created by the merchant.
Second number price is the price in LLD
Third argument toId is the merchants address on the Liberland chain
Callback is the redirect after successful payment
Remark is the note that will be recorded onchain and it can contain identifying info
Failure is the redirect on failure
Hook is a webhook that will return the data about the payment
A payment is considered complete when a payment is sent to the correct address with the correct remark and amount within the next 10000 blocks.
The happy path works in this order:
Merchant creates the payment link
User clicks on the link and executes the payment
User is redirected to the site and a webhook provides data about the payment - address, price and remark
The merchant verifies that the webhook data received matches the order regarding address, price and (optionally) remark
Merchant executes the order
Any failed orders where LLD was sent can be easily handled manually via https://chainscan.mainnet.liberland.org/
Verifying payment
Check signature
Webhook gets data from api.blockchain.liberland.org with a header signature signed with public key, which can be verified. The key is
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0ZkjqOz50GILaxdHvCQJ
egKwmTxsLj5AnDDUhp/n2RSafDjFJ5XIB4zhB+mDfzW+jQMFm0unhlVUD858L8H6
Q/c9nUGbVZMU4seYUJUEwCbcWXqqzg4J0nTIKQjZ2EKT/11ZYQY8HmKs0E35kI18
zNBzgShTn5TDdknjrvMNQn4/EpYg8FR1nELnYIYV92tQH1VExYlinFEM3k8dTUiC
+0Ve3+B2MrFJau9mu3IHUSIQa4/kVX0oSNXOfgRkV3bBAKpST9Re7KXWWCJ7JOhx
bKmy1MRrhiWc8nYS8eieALKgfS+kMgVKQynsFjI4ifGGO8vwnZZXIzblkjMhJGyR
wQIDAQAB
-----END PUBLIC KEY-----The verification pseudocode is
import { readFileSync } from "fs";
import { createVerify, randomBytes } from "crypto";
const publicKey = readFileSync(pubKeyPath, "utf-8");
const verifier = createVerify("SHA256");
verifier.update(responseJSONStringified);
verifier.end();
const signatureBuffer = Buffer.from(signature, "base64");
return verifier.verify(publicKey, signatureBuffer);
// pubKeyPath is the file path to public key
// responseJSONStringified and signature are parameters
// responseJSONStringified is the whole response, JSON stringifiedCheck chain
Alternatively the merchant can check the chain directly or call the middleware API for payment status
endpoint is /verify-purchase with orderId, price and toId POST parameters.
Mainnet https://api.blockchain.liberland.org/v1/verify-purchase
Testnet https://staging.api.blockchain.liberland.org/v1/verify-purchase
Upcoming v1.5
Upcoming version 1.5 will integrate with companies on Liberland chain. The hook, success and fail callbacks will be setup during company registration and will not be included in the link generated by merchant but read from the chain directly to add additional layer of security.
Companies will be able to have multiple addresses.
Companies will be able to see a history of transactions on the blockchain for all addresses as well as failed transactions, acting as history and metrics.
Upcoming v2.0
Each order will be an unique walletaddress that the company controls, so the orders will be able to be completed not only in blockchain.liberland.org but any substrate wallet
Last updated