Skip to Content
DocsAPI ReferenceDirect API Integration

Direct API Integration Guide

Overview

This guide is for developers who already have their own servers and want to integrate KryptoGO payment APIs directly. We’ll walk through the typical payment workflow and explain how to call the Payment Intents API at each step.

Before proceeding, make sure you have obtained your API key from KryptoGO Studio. If you haven’t done this yet, please refer to the Getting Started Guide.

Payment Intent Workflow

  1. Create Payment Intent - Generate a payment intent when a user wants to make a payment
  2. Monitor Payment Status - Track the status of the payment using polling or callbacks
  3. Process Token Transfers - Handle asset transfers for withdrawals
⚠️

All API calls should be made from your server, not client-side code, to protect your API credentials.

Creating a Payment Intent

When a user wants to make a payment, you’ll need to create a payment intent. This will generate payment information that the user can use to complete their transaction.

API Call

const axios = require('axios');
 
async function createPaymentIntent(fiatAmount, fiatCurrency, callbackUrl, orderData, groupKey) {
  try {
    const response = await axios.post(
      'https://wallet.kryptogo.app/v1/studio/api/payment/intent',
      {
        fiat_amount: fiatAmount,
        fiat_currency: fiatCurrency,
        callback_url: callbackUrl,
        order_data: orderData,
        group_key: groupKey
      },
      {
        headers: { 
          'Content-Type': 'application/json',
          'X-Client-ID': 'YOUR_CLIENT_ID',
          'Origin': 'YOUR_DOMAIN',
          'X-STUDIO-API-KEY': 'YOUR_API_KEY'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error creating payment intent:', error);
    throw error;
  }
}

Response Handling

The API will return a payment intent object with details such as:

  • Payment address (where the user should send funds)
  • Crypto amount (how much cryptocurrency to send)
  • Payment deadline (when the payment expires)
  • Status (pending, success, expired, insufficient_not_refunded, insufficient_refunded)

Example response:

{
  "code": 0,
  "data": {
    "payment_intent_id": "2MFV9kRD0IyNWauowhq2Bp3IUb3BWKPi",
    "payment_chain_id": "arb",
    "payment_address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "token_address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
    "symbol": "USDT",
    "decimals": 6,
    "crypto_amount": "9.23",
    "fiat_amount": "300.0",
    "fiat_currency": "TWD",
    "payment_deadline": 1733811354,
    "status": "pending",
    "payment_tx_hash": null,
    "refund_tx_hash": null,
    "received_amount": null,
    "aggregated_amount": null,
    "refund_amount": null,
    "order_data": {
      "order_id": "uid_12345",
      "item_id": "100",
      "customer_id": "0x03971234567890"
    },
    "callback_url": "https://example.com/callback",
    "group_key": "buy_stone_with_usdt"
  }
}

Present this information to your users or redirect them to your payment page where they can complete the transaction.

Monitoring Payment Status

You have two options for monitoring payment status:

Option 1: Using Callback URL

When creating a payment intent, provide a callback_url parameter. KryptoGO will send a POST request to this URL when the payment status changes.

  1. Set up an endpoint on your server to receive these callbacks:
// Using Express.js
app.post('/webhook', (req, res) => {
  const paymentUpdate = req.body;
  
  // Verify the payment data (recommended)
  // Process the payment update based on status
  switch(paymentUpdate.status) {
    case 'success':
      // Payment completed successfully
      console.log('Payment successful!', {
        txHash: paymentUpdate.payment_tx_hash,
        receivedAmount: paymentUpdate.received_amount,
        aggregatedAmount: paymentUpdate.aggregated_amount
      });
      break;
    case 'expired':
      // Payment window closed without receiving funds
      console.log('Payment expired', paymentUpdate);
      break;
    case 'insufficient_not_refunded':
      // User sent too little - waiting for refund
      console.log('Insufficient payment, pending refund', paymentUpdate);
      break;
    case 'insufficient_refunded':
      // Refund completed
      console.log('Insufficient payment refunded', {
        refundTxHash: paymentUpdate.refund_tx_hash,
        refundAmount: paymentUpdate.refund_amount
      });
      break;
  }
  
  // Respond to acknowledge receipt
  res.status(200).send('Webhook received');
});

Option 2: Polling for Status

If you don’t want to use callbacks, you can poll the payment intent status periodically:

async function checkPaymentStatus(paymentIntentId) {
  try {
    const response = await axios.get(
      `https://wallet.kryptogo.app/v1/studio/api/payment/intent/${paymentIntentId}`,
      {
        headers: { 
          'X-Client-ID': 'YOUR_CLIENT_ID',
          'Origin': 'YOUR_DOMAIN',
          'X-STUDIO-API-KEY': 'YOUR_API_KEY'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error checking payment status:', error);
    throw error;
  }
}
⚠️

When polling, be mindful of API rate limits. Don’t check status too frequently.

Processing Token Transfers (Withdrawals)

When users want to withdraw funds from your application, you can use the Asset Pro Transfer API:

async function transferTokens(chainId, contractAddress, amount, walletAddress) {
  try {
    const response = await axios.post(
      'https://wallet.kryptogo.app/v1/studio/api/asset_pro/transfer',
      {
        chain_id: chainId,
        contract_address: contractAddress,
        amount: amount,
        wallet_address: walletAddress
      },
      {
        headers: { 
          'X-STUDIO-API-KEY': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Error transferring tokens:', error);
    throw error;
  }
}

Example successful response:

{
  "code": 0,
  "data": {
    "id": "1-1627380000-1",
    "tx_hash": "0x1234567890abcdef",
    "transfer_time": 1627380000
  }
}

The API will return a transaction hash that you can use to track the transfer on the blockchain.

Error Handling Best Practices

When integrating with payment APIs, robust error handling is crucial:

  1. Validate Inputs: Always validate parameters before sending to the API
  2. Handle Network Errors: Implement retries for transient network issues
  3. Log API Responses: Keep detailed logs for debugging
  4. Handle Edge Cases: Plan for all possible payment statuses, not just success

Security Considerations

  1. API Key Protection: Never expose your API key in client-side code
  2. HTTPS: Use HTTPS for all API requests
  3. Webhook Validation: Validate webhook payloads to prevent spoofing
  4. Rate Limiting: Implement rate limiting on your webhook endpoints

Next Steps

For complete API documentation including all available endpoints, parameters, and response formats, please refer to our API Reference .

Example Server SetupChains