Gaian Pay

Welcome to the official Gaian Pay API documentation. This document provides all the information you need to integrate Gaian Pay's powerful payment solutions into your application or service, enabling

🚀 Getting Started: A Quick Start Guide

Follow these simple steps to start accepting payments with Gaian Pay.

Flow Gaian Network API

Step 1: Obtain Your API Credentials

  • To get started, you'll need a Gaian Pay merchant account.

  • Once your account is approved, you can find your apiKey and apiSecret in your dashboard under Developer Settings. These credentials are used to authenticate your API requests.

Step 2: Set Up Your Environment

Gaian Pay provides two environments:

  • Sandbox: For testing and integration. No real money is involved.

  • Base URL: https://api.sandbox.gaian.network

  • Production: For live transactions with real customers.

  • Base URL: https://api.gaian.network

Step 3: Make Your First API Call

Use our SDKs or make direct HTTP requests to our API. Let's try to check your wallet balance. Remember to replace {apiKey} with your actual key and generate a valid signature.

curl -X POST 'https://api.sandbox.gaian.network/v1/account/balance'
--header 'Content-Type: application/json'
--header 'apiKey: YOUR_API_KEY'
--data-raw '{
"timestamp": 1678886400000,
"nonce": "a1b2c3d4e5f6",
"signature": "GENERATED_SIGNATURE"
}'

🔑 Core Concepts

1. Authentication & Digital Signature

All private API requests to Gaian Pay must be digitally signed to ensure security and integrity. Unsigned or incorrectly signed requests will be rejected.

How it works:

The signature is a HMAC-SHA256 hash of a pre-defined string, using your apiSecret as the key.

String to Sign:

The string is a concatenation of the request body (as a JSON string), your apiKey, a nonce (a random string unique to each request), and a timestamp (in milliseconds).

stringToSign = JSON.stringify(requestBody) + apiKey + nonce + timestamp

Generating the Signature:

Example (Node.js):

const crypto = require('crypto');
const requestBody = { /* your request payload */ };
const apiKey = 'YOUR_API_KEY';
const apiSecret = 'YOUR_API_SECRET';

const nonce = Date.now().toString(); // Or any unique string
const timestamp = Date.now();
const bodyString = JSON.stringify(requestBody);
const stringToSign = bodyString + apiKey + nonce + timestamp;

const signature = crypto
.createHmac('sha256', apiSecret)
.update(stringToSign)
.digest('hex');

All signed requests must include the apiKey, nonce, and timestamp values in the request body, along with the generated signature.

2. Webhooks (IPN)

Webhooks, also known as Instant Payment Notifications (IPN), are essential for getting real-time updates on transaction statuses. Instead of constantly polling our API, Gaian Pay can send an HTTP POST request to a URL you specify (ipnUrl) whenever a transaction is created, updated, or completed.

To use webhooks:

  • Provide a publicly accessible ipnUrl when you create an order.

  • Your server should listen for incoming POST requests at this URL.

  • When you receive a notification, you must verify its authenticity by validating the digital signature included in the request header. This process is the same as signing an outgoing request.

  • After successful verification, your server should respond with a 200 OK status code. If Gaian Pay does not receive a 200 OK, it will retry sending the notification several times.

Webhook Payload Example:

{
  "orderId": "ORD-12345XYZ",
  "transactionId": "TRX-ABCDEF987",
  "status": "COMPLETED",
  "amount": "1500.00",
  "currency": "USD",
  "timestamp": 1678886400000,
  "signature": "RSSAH....Ddsds212dsry"
}

3. Regulations & Requirements

To use Gaian Pay, you must comply with all applicable financial regulations in your jurisdiction. Your account must be verified (KYC/KYB) before you can access the Production environment. Prohibited activities include illegal goods/services, gambling (in unsupported regions), and fraudulent activities.

📖 API Reference

Account Management

Get Account Wallet Balance

Retrieves the balance for all currencies in your Gaian Pay wallet.

  • Endpoint: POST /v1/account/balance

  • Request Body:

Field
Type
Required
Description

partnerCode

string

Yes

The code of partner has been provided to you during onboarding.

currency

string

Yes

The cryptocurrency need to check the current balance on account wallet USDT | USDC | ...

signature

string

Yes

  • Partner will digitally sign the transmitted data using SHA256 with RSA algorithm

  • The public key that has been provided to you during onboarding.

  • Data shall be signed according to the structure partnerCode|currency|secretKey

  • Success Response (200 OK):

{
  "status": "success",
  "data": {
  "balances": [
      {
        "currency": "USDT",
        "availableBalance": "10000.50",
      },
      {
        "currency": "USDC",
        "availableBalance": "10000.512345",
      }
    ],
    "signature": "RSSAH....Ddsds212dsry"
  }
}

Verify Your Account

Checks if the API credentials (apiKey and apiSecret) are valid.

  • Endpoint: POST /v1/account/verify-account

  • Request Body:

Field
Type
Required
Description

partnerCode

string

Yes

The code of partner has been provided to you during onboarding.

signature

string

Yes

  • Partner will digitally sign the transmitted data using SHA256 with RSA algorithm

  • The public key that has been provided to you during onboarding.

  • Data shall be signed according to the structure partnerCode|secretKey

  • Success Response (200 OK):

{
  "name": "PartnerName",
  "email": "[email protected]",
  "status": "active",  // inactive | active
  "signature": "RSSAH....Ddsds212dsry"
}

Check Cryptocurrencies Price

Retrieves the current market price of supported cryptocurrencies.

  • Endpoint: GET /v1/price

  • Query Parameters:

Field
Type
Required
Description

partnerCode

string

Yes

The code of partner has been provided to you during onboarding.

currencies

string

Yes

The cryptocurrency need to check the current balance on account wallet USDT | USDC | ...

network

string

Yes

the cryptocurrency network need to exchange. For example: ERC20,TON

fiatCurrency

string

No

The fiat currency

  • VND: Viet Nam

signature

string

Yes

  • Partner will digitally sign the transmitted data using SHA256 with RSA algorithm

  • The public key that has been provided to you during onboarding.

  • Data shall be signed according to the structure partnerCode|currencies|network|secretKey

  • Success Response (200 OK):

{
  "status": "success",
  "data": {
    "status": "success",
    "data": {
      "USDT": { "USD": 65000.50, "VND": 1650000000 },
      "USDC": { "USD": 3500.20, "VND": 89000000 }
    },
    "signature": "RSSAH....Ddsds212dsry"
  }

}

Verify Bank Account

Validates bank account details.

  • Endpoint: POST /v1/account/verify-bank-account

  • Request Body:

Field
Type
Required
Description

partnerCode

string

Yes

The code of partner has been provided to you during onboarding.

bankCode

string

Yes

The bank code with supported here for example: VIETCOMBANK

bankAccountNumber

string

Yes

the bank account number of your customer

signature

string

Yes

  • Partner will digitally sign the transmitted data using SHA256 with RSA algorithm

  • The public key that has been provided to you during onboarding.

  • Data shall be signed according to the structure partnerCode|bankCode|bankAccountNumber|secretKey

  • Success Response (200 OK):

{
  "bankCode": "VIETCOMBANK",
  "bankAccountNumber": "1023020330000",
  "bankAccountName": "Nguyen Van A",
  "signature": "RSSAH....Ddsds212dsry"
}

Get List of Supported Banks

Retrieves a list of all banks supported by Gaian Pay for payouts.

  • Endpoint: GET /v1/banks

  • Request Body:

Field
Type
Required
Description

partnerCode

string

Yes

The code of partner has been provided to you during onboarding.

fiatCurrency

string

Yes

The fiat currency with supported here for example: VND, ...

signature

string

Yes

  • Partner will digitally sign the transmitted data using SHA256 with RSA algorithm

  • The public key that has been provided to you during onboarding.

  • Data shall be signed according to the structure partnerCode|fiatCurrency|secretKey

  • Success Response (200 OK):

{
  "status": "success",
  "data": {
    "banks":[
      {
        "name": "Vietcombank",
        "code": "VCB",
        "logo": "https://example.com/vcb.png"
      },
      {
        "name": "Techcombank",
        "code": "TCB",
        "logo": "https://example.com/tcb.png"
      }
    ],
    "signature": "RSSAH....Ddsds212dsry"
  }
}

Orders

Create an Order

Creates a new payment order. An order represents a request for payment from a customer.

  • Endpoint: POST /v1/orders/create

  • Request Body:

Field
Type
Required
Description

partnerCode

string

Yes

The code of partner has been provided to you during onboarding.

currency

string

Yes

The currency of the order (e.g., USDC, USDT,..).

fiatCurrency

string

Yes

Supported fiat currencies (e.g, VND,...)

fiatAmount

number

Yes

The amount of fiat (VND) the user wants to pay.

bankCode

string

yes

The webhook URL for real-time status updates.

bankAccountNumber

string

yes

bank account number wants to send to fiat.

content

string

No

Content of transaction.

webhookSecretKey

string

yes

It is secret key created by partner dashboard.

externalOrderId

string

yes

This unique id for order created and managed in partner side. It will keep the update for transaction status after created it.

signature

string

Yes

  • Partner will digitally sign the transmitted data using SHA256 with RSA algorithm

  • The public key that has been provided to you during onboarding.

  • Data shall be signed according to the structure partnerCode|externalOrderId|currency|fiatAmount|bankCode|bankAccountNumber|content|secretKey

qrType

qrType

yes

in Vietnam: "vietqr".

countryCode

string

yes

the countryCode getting from api get the information of QRCode.

  • Success Response (200 OK):

{
  "status": "success",
  "data": {
    "fiatAmount": 0,
    "paidAmount": 0,
    "tokenTransfer": {
      "currency": "string",
      "network": "string",
      "price": 0,
      "amount": 0,
      "walletAddress": "string",
      "txHash": "string"
    },
    "bankTransfer": {
      "bankAccountName": "string",
      "bankAccountNumber": "string",
      "bankName": "string",
      "contentPayment": "string",
      "totalPayment": 0,
      "qrUrl": "string"
    },
    "fees": {
      "systemFee": 0,
      "processingFee": 0
    },
    "status": "string", // AWAITING_PAYMENT | PAYMENT_COMPLETED | PROCESSING_TOKEN_TRANSFER | SUCCESS | ERROR 
    "description": "string",
    "createdAt": "string",
    "expiresAt": "string",
    "signature": "string"
  }
}

Transactions

Get Transaction Details

Retrieves the details and current status of a specific transaction.

  • Endpoint: POST /v1/transactions/detail

  • Request Body:

Field
Type
Required
Description

partnerCode

string

Yes

The code of partner has been provided to you during onboarding.

externalOrderId

string

yes

This unique id for order created and managed in partner side. It will keep the update for transaction status after created it.

signature

string

Yes

  • Partner will digitally sign the transmitted data using SHA256 with RSA algorithm

  • The public key that has been provided to you during onboarding.

  • Data shall be signed according to the structure partnerCode|externalOrderId|secretKey

  • Success Response (200 OK):

{
  "externalOrderId": "string",
  "type": "string",
  "fiatAmount": 0,
  "paidAmount": 0,
  "tokenTransfer": {
    "currency": "string",
    "network": "string",
    "price": 0,
    "amount": 0,
    "walletAddress": "string",
    "txHash": "string"
  },
  "bankTransfer": {
    "bankAccountName": "string",
    "bankAccountNumber": "string",
    "bankName": "string",
    "contentPayment": "string",
    "totalPayment": 0,
    "qrUrl": "string"
  },
  "fees": {
    "systemFee": 0,
    "processingFee": 0
  },
  "status": "string", // AWAITING_PAYMENT | PAYMENT_COMPLETED | PROCESSING_TOKEN_TRANSFER | SUCCESS | ERROR 
  "description": "string",
  "createdAt": "string",
  "expiresAt": "string",
  "signature": "string"
}

Public Endpoints

Get Information of QR Code

Retrieves public order information associated with a Gaian Pay QR code. This endpoint does not require a signature.

  • Endpoint: GET /v1/public/qr-info

  • Query Parameter:

Field
Type
Required
Description

qrData

string

Yes

The data string obtained from scanning a Gaian Pay QR code.

  • Success Response (200 OK):


{
  "status": "success",
   "data": {
        "bankAccountNumber": "99MM23240M34032875",
        "bankCode": "VietCapitalBank",
        "bankName": "Ngân hàng TMCP Bản Việt",
        "countryCode": "VN",
        "qrType": "vietqr"
    },
}
NextTerms of Service

Last updated