API Documentationeer

Overview

This document will guide you step by step to implement our API service. Here is the API flow with its example.

You may need to refer to these environment URLs:

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

Payment: https://dev-payments.gaian-dev.network
User: https://dev-user.gaian-dev.network

Production: For live transactions with real customers.

Payment:https://payments.gaian-dev.network
User:https://user.gaian-dev.network

You can have a look at the general sequence diagram.

API Key

Step 1: Add API Key to Request Header

You will need to add API Key field to Header of every Requests as following:

"x-api-key": "api_key"

User Registeration flow

With this flow follow User path

Step 1: User Register

Step 1.1: User Register (Register and KYC on Gaian side)

You will need to make a POST request to /api/v1/user/register

POST /api/v1/user/register

Resquest
{
	email: "[email protected]",(Optional)
	walletAddress: "abcd...feg234"
}

Response
{
  status: "success",
  message: "User registered successfully",
  user: { id: 18, email: "[email protected]" }
}

If you want to do KYC on your side and want to share it, make user flow more smoothly, you can use this KYC Sharing API

Users must be registered via the /user/register API; automatic creation is no longer supported.

You need to make a POST request to api/v1/submit-kyc-information

POST api/v1/submit-kyc-information

Request
{
	userWalletAddress: "abcd....132ds"
	userEmail: "[email protected]",
	firstName: "A",
	lastName: "Nguyen Van",
	dateOfBirth: "1996-10-10", #YYYY-MM-DD
	gender: "male", # ["male","female"]
	nationality: "VN",
	type: "ID_CARD", # ["ID_CARD","PASSPORT"]
	nationalId: "12130163",
	issueDate: "2020-06-06", #YYYY-MM-DD
	expiryDate: "2030-06-06", #YYYY-MM-DD
	addressLine1: "Ho Chi Minh",
	addressLine2: "Go Vap",
	city: "Ho Chi Minh",
	state: "Ho Chi Minh",
	zipCode: "70000",
	frontIdImage: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/.........", #Base 64 string
	backIdImage: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/.........", #Base 64 string
	holdIdImage: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/.........", #Base 64 string
	phoneNumber: "0968861116",
	phoneCountryCode: "84",
}

Response
{
	success: true,
	message: "KYC submitted successfully",
	data: {
		user: "[email protected]",
		walletAddress: "abcd....132ds",
		kycStatus: "status" #Status gonna have:["not started", "under review", "approved", "rejected"]
	}
}

Step 2: User KYC

User need to be KYC-ed to be able to make a payment. You will need to make a POST request to /api/v1/kyc/link

POST /api/v1/kyc/link

Request
{
  email: "[email protected]", (Optional)
  walletAddress: "wallet_address_string"
}

Response
{
	success: true ,
	message: "KYC external link generated successfully",
	websdkUrl: "<https://linktokyc/websdk/p/example.com>",
}

Payment Flow

With this flow follow Payment path

Step 1: Place Order

Step 1.1: Place Order (Without Prefunded)

You will need to make a POST request to /api/v1/placeOrder

⚠️Please be caution: These QR string was meant to be use in SANDBOX. DO NOT USE IT IN PRODUCTION

To test with VND please use this QR String:

qrString: "00020101021126400010vn.zalopay0115uvsgayNI4Xsrqwz020300238620010A00000072701320006970454011899ZP24250M421803650208QRIBFTTA5204739953037045802VN63041428"

To test with PHP please use this QR String:

qrString: "00020101021127590012com.p2pqrpay0111UBPHPHMMXXX02089996440304121096459500755204601653036085802PH5925Sophia Marie Chavez Dever6009SAN PEDRO63043708"

POST /api/v1/placeOrder

Request
{
  qrString: "qrString",
  amount: 10, #Please test with the amount higher than 50,000 VND or 10 PHP
  fiatCurrency: "PHP", #Currently supported ["VND", "PHP"]
  cryptoCurrency: "USDC",  #Currently only USDC supported
  chain: "Solana", #Currently supported ["Solana", "Ethereum", "Polygon", "Arbitrum", "Base"]
  fromAddress: "fromWalletAddress",
  transactionReference: "Custom label - defaults to Crypto payout {orderId}" (Optional)
}

Response
{
  "orderId": "order_id",
  "status": "awaiting_crypto_transfer",
  "fiatAmount": 10,
  "fiatCurrency": "PHP",
  "cryptoAmount": 0.3329508,
  "cryptoCurrency": "USDC",
  "exchangeRate": 58.50346529177664,
  "qrInfo": {
      "encodedString": "00020101021127590012com.p2pqrpay0111UBPHPHMMXXX02089996440304121096459500755204601653036085802PH5925Sophia Marie Chavez Dever6009SAN PEDRO63043708",
      "providerInfo": {
          "name": "com.p2pqrpay",
          "service": "UNION BANK OF THE PHILIPPINES"
      },
      "bankInfo": {
          "bankBin": "UBPHPHMM",
          "bankNumber": "109645950075"
      },
      "additionalData": "{\\"merchantMobileNumber\\":\\"\\",\\"merchantCity\\":\\"SAN PEDRO\\",
										      \\"crcCode\\":\\"3708\\",\\"purpose\\":\\"\\",\\"mobileNumber\\":\\"\\",
										      \\"tfrName\\":\\"Sophia Marie Chavez Dever\\",\\"tfrBnkCode\\":\\"UBPHPHMMXXX\\",
										      \\"userId\\":\\"\\",\\"paymentType\\":\\"99964403\\",\\"customerLabel\\":\\"\\",
										      \\"merchantCategoryCode\\":\\"6016\\",\\"tfrAcctNo\\":\\"109645950075\\",\\"postCode\\":\\"\\",
										      \\"uniqueId\\":\\"com.p2pqrpay\\",\\"loyaltyNumber\\":\\"\\"}",
      "beneficiaryName": "Sophia Marie Chavez Dever",
      "countryCode": "PH"
  },
  "cryptoTransferInfo": {
      "chain": "Solana",
      "fromAddress": "CKhbBVLBCYaRH6GFP7TXs3PBrKkbLys9WvDs5Mm7UuLH",
      "toAddress": "FK2ABh32TKMHgZRQKrxAQqopcs8Gm4igPB4s2roUCKJb",
      "token": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
      "amount": 332951,
      "encodedTransaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAQABBKg6575mmykdPEHBGvqzj3YdwYf/J7jO9ng5O+x57uTG/xZ9DjASbM7EGxZeyxmfQhR/gQWXvfemaKfwEv3Kz2tm09cpQsp1a9JslSMyq8KzlUACfcX9FMqjwWKIwPl8/wbd9uHXZaGT2cvhRs7reawctIXtX1s3kTqM9YV+/wCpfYXAvMSOOX463KV9P2vHV03BrbYR/die/tndzaBb9VsBAwMBAgAJA5cUBQAAAAAAAA=="
  },
  "timestamp": "2025-12-02T08:05:29.588Z",
  "transactionReference":"Crypto payout {orderId}"
}

Step 1.2: Place Order (With Prefunded)

To use this flow please reach out to us.

You will need to make a POST request to /api/v1/placeOrder/prefund

After place an order, it will be proceeded automatically.

⚠️Please be caution: These QR string was meant to be use in SANDBOX. DO NOT USE IT IN PRODUCTION

To test with VND please use this QR String:

qrString: "00020101021126400010vn.zalopay0115uvsgayNI4Xsrqwz020300238620010A00000072701320006970454011899ZP24250M421803650208QRIBFTTA5204739953037045802VN63041428"

To test with PHP please use this QR String:

qrString: "00020101021127590012com.p2pqrpay0111UBPHPHMMXXX02089996440304121096459500755204601653036085802PH5925Sophia Marie Chavez Dever6009SAN PEDRO63043708"

POST /api/v1/placeOrder/prefund

Request
{
  qrString: "qrString",
  amount: 10, #Please test with the amount higher than 50,000 VND or 10 PHP
  fiatCurrency: "PHP", #Currently supported ["VND", "PHP"]
  cryptoCurrency: "USDC", #Currently supported ["USDC", "USDT"]
  fromAddress: "fromWalletAddress", #User wallet for reference
  transactionReference: "Custom label - defaults to Crypto payout {orderId}" (Optional)
}

Response
{
	"orderId":"order_id",
	"status":"awaiting_crypto_transfer",
	"fiatAmount":10,
	"fiatCurrency":"PHP",
	"cryptoAmount":0.1709,
	"cryptoCurrency":"USDC",
	"exchangeRate":58.52906449777173,
	"qrInfo":
		{
			"encodedString":"00020101021127590012com.p2pqrpay0111UBPHPHMMXXX02089996440304121096459500755204601653036085802PH5925Sophia Marie Chavez Dever6009SAN PEDRO63043708",
			"providerInfo":{},
			"bankInfo":{},
			"beneficiaryName":"Sophia Marie Chavez Dever",
			"additionalData":"{\\"merchantMobileNumber\\":\\"\\",\\"merchantCity\\":\\"SAN PEDRO\\",
												\\"crcCode\\":\\"3708\\",\\"purpose\\":\\"\\",\\"mobileNumber\\":\\"\\",
												\\"tfrName\\":\\"Sophia Marie Chavez Dever\\",\\"tfrBnkCode\\":\\"UBPHPHMMXXX\\",
												\\"userId\\":\\"\\",\\"paymentType\\":\\"99964403\\",\\"customerLabel\\":\\"\\",
												\\"merchantCategoryCode\\":\\"6016\\",\\"tfrAcctNo\\":\\"109645950075\\",
												\\"postCode\\":\\"\\",\\"uniqueId\\":\\"com.p2pqrpay\\",\\"loyaltyNumber\\":\\"\\"}"
		},
	"cryptoTransferInfo":
			{
				"chain":"solana",
				"fromAddress":"CKhbBVLBCYaRH6GFP7TXs3PBrKkbLys9WvDs5Mm7UuLH",
				"toAddress":"FK2ABh32TKMHgZRQKrxAQqopcs8Gm4igPB4s2roUCKJb",
				"token":"4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
				"amount":0.1709
			},
	"timestamp":"2025-12-02T08:01:26.914Z",
	"isPrefunded":true,
	"transactionReference":"Crypto payout {orderId}"
	}

Step 2: Build and Sign the Transaction

Please notice⚠️: Skip this step if you’re using Prefunded flow.

This will need to be perform on your side. You will need a build instruction function, example in TypeScript:

  decodeTransaction = async (
    data: PlaceOrderResponse
  ): Promise<Transaction> => {
    if (!this.solanaConnection)
      throw new Error(Solana connection not defined);

    const { blockhash } = await this.solanaConnection.getLatestBlockhash(
      confirmed
    );

    const transferInstruction = await buildSolanaSendTransactionInstruction(
      new PublicKey(data.cryptoTransferInfo.fromAddress),
      new PublicKey(data.cryptoTransferInfo.toAddress),
      new PublicKey(data.cryptoTransferInfo.token),
      data.cryptoTransferInfo.amount
    );

    // Create Legacy Transaction instead of VersionedTransaction
    const transaction = new Transaction();
    transaction.add(transferInstruction);
    transaction.recentBlockhash = blockhash;
    transaction.feePayer = new PublicKey(data.cryptoTransferInfo.fromAddress);

    return transaction;
  };

Then sign and submit the transaction to chain.

Step 3: Verify Order

Please notice⚠️: Skip this step if you’re using Prefunded flow.

After submitting the transaction to chain, you will need to make a POST request with the transaction hash (tx_Hash) hash and order Id ( order_id_string), to /api/v1/verifyOrder

POST /api/v1/verifyOrder

Request
{
	orderId: "order_id_string",
	transactionProof: "tx_Hash"
}

Response
{
	orderId: "order_id_string",
	status: "verified" , #List of status: awaiting_crypto_transfer, verified, processing, failed or completed
	transactionHash: "tx_Hash",
	message: "Transaction verified and bank transfer queued", 
	bankTransferStatus: "queued"
}

Step 4: Polling the Status

After the order is verified , it will be auto-processing. Then you will need to make a polling function to make a GET request to /api/v1/status after an amount of time

GET /api/v1/status

Request
{
	orderId: "order_id_string"
}

Response (Processing)
{
  id: 138,
  orderId: "order_id_string",
  status: "processing",
  fiatAmount: 20000,
  fiatCurrency: "VND",
  cryptoAmount: 0.8,
  cryptoCurrency: USDC,
  exchangeRate: 26000,
  qrInfo: {
    bankInfo: {
      bankBin: "123456",
      bankNumber: "567891"
    },
    providerInfo: {
      guid: "A000000727",
      name: "VIETQR",
      service: "QRIBFTTA"
    },
    encodedString: "qrString"
  },
  paymentMethod: "qr_code",
  expiresAt: "timeStamp",
  bankTransactionReference: {},
  createdAt: "timeStamp",
  updatedAt: "timeStamp",
  userId: null,
  transactionHash: "tx_Hash",
  pollCount: 24,
  lastChecked: "time"
}

Response (Completed)
{
  id: 138,
  orderId: "order_id_string",
  status: "completed",
  fiatAmount: 20000,
  fiatCurrency: "VND",
  cryptoAmount: 0.8,
  cryptoCurrency: USDC,
  exchangeRate: 26000,
  qrInfo: {
    bankInfo: {
      bankBin: "123456",
      bankNumber: "567891"
    },
    providerInfo: {
      guid: "A000000727",
      name: "VIETQR",
      service: "QRIBFTTA"
    },
    encodedString: "qrString"
  },
  paymentMethod: "qr_code",
  expiresAt: "timeStamp",
  bankTransactionReference: {
	  requestId: "require_id",
	  requestDate "timeStamp"
  },
  createdAt: "timeStamp",
  updatedAt: "timeStamp",
  userId: null,
  transactionHash: "tx_Hash",
  pollCount: 24,
  lastChecked: "time"
}

Additional API

Parse QR API

With this flow follow Payment path

You will need to make a POST request to /api/v1/parseQr

POST /api/v1/parseQr

Request
{
	qrString: "Qr_string",
	country: "VN"
}

Response
{
	success: true ,
	qrInfo: {
		isValid: true ,
		encodedString: "Qr_string",
		country: "VN",
		qrProvider: "VIETQR",
		bankBin:  "123456",
		accountNumber: "567891",
		currency: "704",
		nation: "VN",
		beneficiaryName: "NGUYEN VAN A",
		detailedQrInfo: {
			provider: {
			 fieldId:  "38",
			 guid:  "A000000727",
			 name:  "VIETQR",
			 data:  "data_string",
			 service:  "QRIBFTTA"
			},
			consumer: {
				bankBin:  "123456",
				bankNumber: "567891",
			},
			merchant: {
			
			},
			additionalData: {
			
			},
			version:  "01",
			initMethod:  "11",
			currency:  "704",
			nation:  "VN",
			crc:  "60C4"
		}
	},
}

Calculate Exchange

With this flow follow Payment path

Calculate cryptocurrency equivalent for fiat amount with current exchange rates

You will need to make a POST request to /api/v1/calculateExchange

POST /api/v1/calculateExchange

Request
{
  amount: 26000,
  country: "VN",
  chain: "Solana",
  token: "USDC"
}

Response
{
  success: true,
  exchangeInfo: {
    fiatAmount: 26000,
    fiatCurrency: "VND",
    cryptoAmount: "0.9846",
    cryptoCurrency: "USDC",
    exchangeRate: "26407.63793324218",
    chain: "Solana",
    token: "USDC",
    timestamp: "timeStamp",
    feeAmount: "fee_Amount"
  }
}

Get Transaction History

With this flow follow User path

By User Email

You will need to make a GET request to /api/v1/users/{User_Email}/orders

GET /api/v1/users/{User_Email}/orders

Request
{
	page: 1, (Optional)
	limit: 5, (Optional)
	status: "completed" (Optional)
}

Response
{
  status: "success",
  data: {
    user: {
      id: 12,
      email: "User_Email",
      walletAddress: "Wallet_Address",
      createdAt: "2025-09-15T04:28:20.451Z",
      updatedAt: "2025-09-15T05:33:57.873Z"
    },
    orders: {
      items: [], #Empty because there are no complete order
      pagination: {
        page: 1,
        limit: 5,
        total: 0,
        totalPages: 0,
        hasNext: false,
        hasPrev: false
      }
    }
  }
}

By User Wallet

You will need to make a GET request to /api/v1/users/wallet/{User_Wallet}/orders

GET /api/v1/users/wallet/{User_Wallet}/orders

Request
{
	page: 1, (Optional)
	limit: 5, (Optional)
	status: "completed" (Optional)
}

Response
{
  status: "success",
  data: {
    user: {
      id: 12,
      email: "User_Email",
      walletAddress: "Wallet_Address",
      createdAt: "2025-09-15T04:28:20.451Z",
      updatedAt: "2025-09-15T05:33:57.873Z"
    },
    orders: {
      items: [], #Empty because there are no complete order
      pagination: {
        page: 1,
        limit: 5,
        total: 0,
        totalPages: 0,
        hasNext: false,
        hasPrev: false
      }
    }
  }
}

Get User Infomation

With this flow follow User path

By User Email or User Wallet Address

You will need to make a GET request to /api/v1/users/?email="?"

Or, you will need to make a GET request to /api/v1/users/?walletAddress="?"

GET /api/v1/users/?email="[email protected]"
Request
{
	"email" :"[email protected]"
}

Response
{
    "status": "success",
    "user": {
        "id": 1,
        "email": "[email protected]",
        "walletAddress": "abdcefghijklmnopqrstuvwxyz",
        "kyc": {
            "status": "approved", //Status gonna have:[not started, under review, approved, rejected]
            "firstName": "John",
            "lastName": "Mock-Doe",
            "country": "VNM",
            "applicantPlatform": "Web",
            "phone": null
        }
    }
}

GET /api/v1/users/?walletAddress="abdcefghijklmnopqrstuvwxyz"

Request
{
	walletAddress:"abdcefghijklmnopqrstuvwxyz"
}

Response
{
    "status": "success",
    "user": {
        "id": 1,
        "email": "[email protected]",
        "walletAddress": "abdcefghijklmnopqrstuvwxyz",
        "kyc": {
            "status": "approved",
            "firstName": "John",
            "lastName": "Mock-Doe",
            "country": "VNM",
            "applicantPlatform": "Web",
            "phone": null
        }
    }
}

API Reference

Get User Transaction History

KYC Sharing

KYC Requirement

NextRegister User

Last updated 13 days ago

hashtagOverview

hashtagAPI Key

hashtagStep 1: Add API Key to Request Header

hashtagUser Registeration flow

hashtagStep 1: User Register

hashtagStep 1.1: User Register (Register and KYC on Gaian side)

hashtagStep 1.2: KYC Sharing (KYC on Partner side)

hashtagStep 2: User KYC

hashtagPayment Flow

hashtagStep 1: Place Order

hashtagStep 1.1: Place Order (Without Prefunded)

hashtagStep 1.2: Place Order (With Prefunded)

hashtagStep 2: Build and Sign the Transaction

hashtagStep 3: Verify Order

hashtagStep 4: Polling the Status

hashtagAdditional API

hashtagParse QR API

hashtagCalculate Exchange

hashtagGet Transaction History

hashtagBy User Email

hashtagBy User Wallet

hashtagGet User Infomation

hashtagBy User Email or User Wallet Address

hashtagAPI Reference

hashtagKYC Requirement

Overview

API Key

Step 1: Add API Key to Request Header

User Registeration flow

Step 1: User Register

Step 1.1: User Register (Register and KYC on Gaian side)

Step 1.2: KYC Sharing (KYC on Partner side)

Step 2: User KYC

Payment Flow

Step 1: Place Order

Step 1.1: Place Order (Without Prefunded)

Step 1.2: Place Order (With Prefunded)

Step 2: Build and Sign the Transaction

Step 3: Verify Order

Step 4: Polling the Status

Additional API

Parse QR API

Calculate Exchange

Get Transaction History

By User Email

By User Wallet

Get User Infomation

By User Email or User Wallet Address

API Reference

KYC Requirement