Quick Start

Introduction

Welcome to the CoinQ Pay documentation. CoinQ Pay supports OpenAPI and check out H5 payment page. You can choose the best way to integrate with CoinQ Pay according to your needs, and we suggest you priority to use the OpenAPI. The below is the quick start guide for the OpenAPI. If you want to use the H5 payment page, please refer to the check out H5 Payment Page.

CoinQ Pay API is a simple and easy-to-use API that allows you to accept cryptocurrency payments on your website or application. You can accept payments in various cryptocurrencies like Ethereum, Binance Coin, USDT, and USDC. CoinQ Pay API provides a simple and secure way to accept payments without the need for a third-party payment processor.

How it works

1. You generate a Ed25519 key pair and register the public key in the CoinQ Pay merchant admin web.

2. Get the supported coins from the CoinQ Pay API.

3. Create a payment order and sign it with your private key.

4. Send the payment order to the CoinQ Pay API.

5. Receive the payment address from the CoinQ Pay API and display it to your customer.

6. Your customer pays.

7. CoinQ Pay sends a webhook notification to your server with the payment data.

8. You verify the webhook notification from the CoinQ Pay API and deliver the goods or services.

Authentication

Generate your API keys

CoinQ Pay API requests are authenticated using Ed25519 signature. Any request that doesn't include signature and public key will return an error.

You can generate key pairs in your local computer and put public key on the admin web.

Python

# pip install cryptography
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey

# Generate a private key for use in the application.
private_key = Ed25519PrivateKey.generate()

# The public key can be obtained from the private key.
public_key = private_key.public_key()

# print the private and public key
print(f'private_key {private_key.private_bytes_raw().hex()}')
print(f'public_key {public_key.public_bytes_raw().hex()}')

Java

package com.example;
// add bouncycastle dependency to your project 
// https://mvnrepository.com/artifact/org.bouncycastle/bcprov-jdk18on
import org.bouncycastle.crypto.AsymmetricCipherKeyPair;
import org.bouncycastle.crypto.generators.Ed25519KeyPairGenerator;
import org.bouncycastle.crypto.params.Ed25519KeyGenerationParameters;
import org.bouncycastle.crypto.params.Ed25519PrivateKeyParameters;
import org.bouncycastle.crypto.params.Ed25519PublicKeyParameters;
import org.bouncycastle.util.encoders.Hex;

import java.security.SecureRandom;

public class Main {
    public static void main(String[] args) {
        Ed25519KeyPairGenerator keyPairGenerator = new Ed25519KeyPairGenerator();
        keyPairGenerator.init(new Ed25519KeyGenerationParameters(new SecureRandom()));
        AsymmetricCipherKeyPair keyPair = keyPairGenerator.generateKeyPair();
        Ed25519PrivateKeyParameters privateKey = (Ed25519PrivateKeyParameters) keyPair.getPrivate();
        Ed25519PublicKeyParameters publicKey = (Ed25519PublicKeyParameters) keyPair.getPublic();

        System.out.println("private_key: " + Hex.toHexString(privateKey.getEncoded()));
        System.out.println("public_key: " + Hex.toHexString(publicKey.getEncoded()));
    }
}

Security Tips: Please save the private key in a secure place. Do not expose it to the public.

Request Headers

Every request header must include below headers.

• x-pay-public-key: Ed25519 public key hex string, must be registered in the system, length 64

• x-pay-timestamp: timestamp in milliseconds, must be within 5 minutes of the current Unix timestamp, length 13

• x-pay-nonce: random string, length 8-32, can be used to prevent replay attacks

• x-pay-signature: Ed25519 signature of the request, hex string, length 128

Signature

The signature is generated by signing the content to be signed with the private key. The content to be signed is the concatenation of the following parts:

• HTTP_METHOD (GET, POST, PUT, DELETE)

• HTTP_REQUEST_PATH (e.g. /v1/coin_price)

• HTTP_REQUEST_QUERY / PARAMS (e.g. ?coin=ETH&currency=USD)

• JSON_STRING_PAYLOAD (get request can be ignored) (e.g. {"coin":"ETH","currency":"USD"})

• NONCE (random string of length 8-32)

• TIMESTAMP (timestamp in milliseconds)

Note: Do not concatenate the parts that are not present, and do not use an empty string to replace them.

e.g.

curl -X POST -H 'Content-Type: application/json' -H 'x-pay-nonce: d9ac796bf1d14c48b1c9d20f9b61fb4b' -H 'x-pay-public-key: 470ae095c58c15e8fef9c584a21e47912209316ab9b4f961e0f01d566a2337cb' -H 'x-pay-signature: bcef4ea9b7a2c36c0e5525b94777849513007e617cad04ce4914341e76d935b5c26a56ed339378635cf60fe2ec657d3b85ea0b3b19b1ed9a2436126d7d1e250f' -H 'x-pay-timestamp: 1720101291916' -d '{"coin": "ETH", "order_id": "OR00000001", "amount": "0.001"}' https://coinqpay.com/api/v1/pay_order

• HTTP_METHOD: POST

• HTTP_REQUEST_PATH: /api/v1/pay_order

• JSON_STRING_PAYLOAD: {"coin": "ETH", "order_id": "OR00000001", "amount": "0.001"}

• NONCE: d9ac796bf1d14c48b1c9d20f9b61fb4b

• TIMESTAMP: 1720101291916

Python

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey

message = 'POST/api/v1/pay_order{"coin": "ETH", "order_id": "OR00000001", "amount": "0.001"}d9ac796bf1d14c48b1c9d20f9b61fb4b1720101291916'
private_key_hex = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
private_key = Ed25519PrivateKey.from_private_bytes(bytes.fromhex('private_key_hex'))
signature = private_key.sign(message.encode()).hex()
print(signature)

Java

package com.example;
import org.bouncycastle.crypto.signers.Ed25519Signer;
import org.bouncycastle.crypto.params.Ed25519PrivateKeyParameters;
import org.bouncycastle.util.encoders.Hex;

import java.nio.charset.StandardCharsets;

public class Main {
    public static void main(String[] args) {
        String message = "POST/api/v1/pay_order{\"coin\": \"ETH\", \"order_id\": \"OR00000001\", \"amount\": \"0.001\"}d9ac796bf1d14c48b1c9d20f9b61fb4b1720101291916";
        String privateKeyHex = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
        Ed25519Signer signer = new Ed25519Signer();
        signer.init(true, new Ed25519PrivateKeyParameters(Hex.decode(privateKeyHex)));
        byte[] messageBytes = message.getBytes(StandardCharsets.UTF_8);
        signer.update(messageBytes, 0, messageBytes.length);
        byte[] signature = signer.generateSignature();
        System.out.println(Hex.toHexString(signature));
    }
}

Server Endpoints

• sandbox: https://sandbox.coinqpay.com/

• production: https://api.coinqpay.com/

Sandbox environment is for testing purposes only. Please use the production environment for live transactions. Sandbox supports all the features of the production environment, but the transactions only on the test net, and the coins are not valuable. You can use the following test net coins to test the payment transactions.

Test Net Chains

• Ethereum: Sepolia Testnet

  • chain id: 1115111

  • faucet: https://cloud.google.com/application/web3/faucet/ethereum/sepolia

  • explorer: https://sepolia.etherscan.io/

• Binance Smart Chain: BSC Testnet

  • chain id: 97

  • faucet: https://testnet.binance.org/faucet-smart

  • explorer: https://testnet.bscscan.com/

• Tron: Shasta

  • faucet: https://shasta.tronex.io/

  • explorer: https://shasta.tronscan.org/

Test Net Coins

• USDC:

  • faucet: https://faucet.circle.com/