Payment Implementation Guide

This guide explains the payment workflow and status changes when using the KryptoGO Payment API.

Payment Workflow Overview

When implementing payments, you’ll need to handle these key steps:

Create a payment intent
Monitor payment status changes via callbacks
Process the final payment outcome

Payment Status Lifecycle

A payment intent will progress through various states:

Status	Description
`pending`	Initial state - waiting for user payment
`success`	Payment received and confirmed
`expired`	Payment window closed without receiving funds
`insufficient_not_refunded`	Received amount was too low, pending refund
`insufficient_refunded`	Insufficient payment has been refunded

Creating Payment Intent

The usePayment Hook provides the simplest way to create payment intents. This Hook handles the complete payment flow, from opening the payment modal to monitoring transaction status.

Basic Usage


import { usePayment } from '@kryptogo/payment';
 
function PaymentComponent() {
  const { openPaymentModal, closePaymentModal, data, isLoading, isSuccess, isError, error } = usePayment();
 
  return (
    <button
      onClick={() =>
        openPaymentModal({
          fiat_amount: '100',
          fiat_currency: 'TWD',
        })
      }
    >
      Pay Now
    </button>
  );
}

Advanced Usage

For payment notifications and custom order tracking, you can include a callback_url and custom order_data:


function AdvancedPaymentComponent() {
  const { openPaymentModal } = usePayment();
 
  const handlePayment = () => {
    openPaymentModal({
      fiat_amount: '100',
      fiat_currency: 'TWD',
      callback_url: 'https://your-server.com/payment/callback',
      order_data: {
        orderId: '12345',
        productName: 'Product Name',
        customerInfo: {
          id: 'user123',
          email: 'user@example.com',
        },
      },
      group_key: 'product_purchase',
    });
  };
 
  return <button onClick={handlePayment}>Process Payment</button>;
}

⚠️

Note: The fiat_amount must be at least 0.01. Requests with values below this threshold will be rejected.

Handling Payment Callbacks

KryptoGO sends callbacks to your server for every status change. Your callback handler needs to:

Verify the payment intent matches your records
Check the payment status
Take appropriate action based on the status
Respond with 200 OK to acknowledge receipt

Node.js (Express)


app.post('/payment/callback', (req, res) => {
  const paymentData = req.body;
  
  // First, verify this is a payment you're expecting
  // Check paymentData.payment_intent_id against your database
  
  switch(paymentData.status) {
    case 'success':
      // Important payment details:
      // - paymentData.payment_tx_hash (blockchain transaction hash)
      // - paymentData.received_amount (actual crypto amount received)
      // - paymentData.aggregated_amount (final amount after fees)
      handleSuccessfulPayment(paymentData);
      break;
      
    case 'expired':
      // Payment window closed without receiving funds
      handleExpiredPayment(paymentData);
      break;
      
    case 'insufficient_not_refunded':
      // User sent too little - waiting for refund
      handleInsufficientPayment(paymentData);
      break;
      
    case 'insufficient_refunded':
      // Refund details:
      // - paymentData.refund_tx_hash (refund transaction hash)
      // - paymentData.refund_amount (amount returned to user)
      handleRefundedPayment(paymentData);
      break;
  }
  
  // Always respond with 200 OK to acknowledge receipt
  res.status(200).send();
});

⚠️

Always verify the payment_intent_id in callbacks matches your records before processing the payment status change.

Sample Callback Payload

Here’s an example of what the callback payload will look like for a successful payment:


{
  "payment_intent_id": "0h39QkYfZps7AUD1xQsj3MDFVLIMaGoV",
  "client_id": "9c5a79fc1117310f976b53752659b61d",
  "fiat_amount": "300.0",
  "fiat_currency": "TWD",
  "payment_deadline": 1715462400,
  "status": "success",
  "payment_chain_id": "arb",
  "symbol": "USDT",
  "crypto_amount": "2.53",
  "payment_tx_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "received_amount": "2.53",
  "aggregated_amount": "2.50", 
  "order_data": {
    "order_id": "uid_12345",
    "item_id": "100"
  },
  "callback_url": "https://example.com/callback",
  "group_key": "buy_stone_with_usdt"
}

Best Practices

Payment Status Handling

Implement idempotent callback processing
Store all status changes for audit purposes
Update user interface to reflect current payment status
Handle timeout/expiration cases gracefully

User Experience

Show clear payment instructions
Provide immediate feedback on status changes
Clear error messages for insufficient payments

Security

Validate all callback data
Keep API keys secure
Log all status transitions
Monitor for unusual payment patterns

For detailed API specifications and error codes, refer to the API reference.

Processing User Withdrawals

Node.js


const axios = require('axios');
 
async function transferTokens(chainId, contractAddress, amount, walletAddress) {
  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-studio-api-key',
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}
 
// Example usage
transferTokens('arb', '0xff970a61a04b1ca14834a43f5de4533ebddb5cc8', '0.01', '0x3fE5aC82B997255b8226abb6aEfd91f405fe2e8e')
  .then(result => {
    console.log('Transfer successful', {
      id: result.data.id,
      txHash: result.data.tx_hash,
      transferTime: result.data.transfer_time
    });
  })
  .catch(error => {
    if (error.response && error.response.data) {
      console.error('Transfer failed', error.response.data);
    } else {
      console.error('Error', error);
    }
  });

Transfer Response Success

A successful transfer response will look like this:


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

Transfer Response Error

An error response for insufficient balance:


{
  "code": 4015,
  "message": "Balance not enough",
  "data": {
    "insufficient_amount": "123.456"
  }
}