Payment Intents API

Overview

The Payment Intents API allows organizations to seamlessly integrate cryptocurrency payments into their applications. Whether you’re building a game, e-commerce platform, or any digital service, this API enables you to accept crypto payments and process withdrawals without managing complex blockchain infrastructure.

Typical Flow

Account Creation - When a user registers for your service, create a KryptoGO account for them using the Custom Auth Login API
Payment Processing - When users want to top up or make purchases, create a payment intent
Status Monitoring - Track the status of payment intents, with updates via callback or polling
Token Transfer - Use the Asset Pro Transfer API to transfer tokens to users when they want to withdraw funds

For game developers: This flow aligns perfectly with in-game purchases and rewards systems. Players can top up their accounts using crypto (steps 1-3) and withdraw their earnings (step 4).

Integration Use Cases

Gaming: Enable players to purchase in-game assets and withdraw earnings
E-commerce: Accept cryptocurrency payments for products and services
Digital Services: Offer subscription payments with crypto
Marketplaces: Facilitate buyer-seller transactions using blockchain technology
Loyalty Programs: Distribute rewards tokens to customers

All of these use cases follow the same basic flow outlined above, with variations in how you implement callbacks and user experiences.

Description

Create or authenticate a user account in the KryptoGO system using your organization’s authentication system. This API uses JWT (JSON Web Token) verification to securely authenticate users from your system.

Prerequisites

⚠️

Before using this API, you need:

Client ID - Contact KryptoGO to get your client ID if you don’t have one
A valid JWT token with user’s information from your system
JWT verification setup (details below)

JWT Verification Setup

To enable secure JWT verification between your system and KryptoGO, you need to provide the following information to KryptoGO:

Field	Description	Example
JWK URL	The URL where your JSON Web Keys (JWK) can be fetched. This allows KryptoGO to verify the signature of tokens issued by your system.	`https://your-domain.com/.well-known/jwks.json`
JWT Audience	The audience claim that should be present in the JWT. This ensures tokens are intended for use with KryptoGO.	`https://wallet.kryptogo.app`
JWT Issuer	The issuer claim that should be present in the JWT. This identifies your system as the token issuer.	`https://auth.your-company.com`
JWT UID Field	The field in your JWT payload that contains the unique user identifier.	`sub` or `user_id`

Your KryptoGO account manager will configure these settings for you after you provide the information. Once configured, you can use the Custom Auth Login API to authenticate users.

JWT Token Requirements

The JWT token you provide should meet these requirements:

Signed using RS256 algorithm with a key from your JWK URL
Contains the correct audience matching what you’ve provided to KryptoGO
Contains the correct issuer matching what you’ve provided to KryptoGO
Contains a unique user identifier in the field specified by the JWT UID Field
Not expired according to the exp claim in the token
Properly formatted according to JWT standards

Example JWT payload structure:


{
  "iss": "https://auth.your-company.com", // Issuer - must match JWT Issuer
  "aud": "https://wallet.kryptogo.app", // Audience - must match JWT Audience
  "exp": 1733811354, // Expiration time (Unix timestamp)
  "iat": 1733811054, // Issued at time
  "sub": "user123", // Subject/User ID - must be in the field specified by JWT UID Field
  "name": "John Doe", // Additional user information
  "email": "john@example.com" // Additional user information
}

Implementing JWT for KryptoGO

Your JWT implementation must align with KryptoGO’s verification requirements:

Key Requirements
- Use RSA or ECDSA keys for signing your tokens
- Publish your public keys at a JWKS endpoint (JSON Web Key Set)
- Include the key ID (kid) in your JWT header that corresponds to a key in your JWKS

JWT Header Requirements


{
  "alg": "RS256", // Algorithm used (RS256, ES256, etc.)
  "typ": "JWT",
  "kid": "your-key-id" // Must match a key ID in your JWKS
}

JWKS Endpoint Format Your JWKS endpoint should return a JSON response in this format:


{
  "keys": [
    {
      "kty": "RSA",
      "kid": "your-key-id",
      "use": "sig",
      "alg": "RS256",
      "n": "base64-encoded-modulus",
      "e": "base64-encoded-exponent"
    }
  ]
}

Implementation Example

Here’s a simple example using Node.js and the jsonwebtoken library:


const jwt = require('jsonwebtoken');
const fs = require('fs');
 
// Read your private key (keep this secure!)
const privateKey = fs.readFileSync('private-key.pem');
 
// Your JWT implementation must include your key ID in the header
function generateToken(userId) {
  const payload = {
    iss: 'https://auth.your-company.com', // Must match your JWT Issuer setting
    aud: 'https://wallet.kryptogo.app', // Must match your JWT Audience setting
    sub: userId, // Assuming 'sub' is your UID field
    exp: Math.floor(Date.now() / 1000) + (60 * 60), // 1 hour expiration
    iat: Math.floor(Date.now() / 1000)
  };
  
  const header = {
    kid: 'your-key-id' // Must match a key in your JWKS
  };
  
  return jwt.sign(payload, privateKey, { 
    algorithm: 'RS256',
    header: header
  });
}

Hosting a JWKS Endpoint

You need to create an endpoint that serves your public keys in JWKS format. Here’s a simplified example:


const { JWK } = require('node-jose');
const fs = require('fs');
const express = require('express');
const app = express();
 
// Load your public key
const publicKey = fs.readFileSync('public-key.pem');
 
// Create a JWKS
async function createJWKS() {
  const key = await JWK.asKey(publicKey, { kid: 'your-key-id', use: 'sig', alg: 'RS256' });
  return { keys: [key.toJSON()] };
}
 
// Serve the JWKS
app.get('/.well-known/jwks.json', async (req, res) => {
  const jwks = await createJWKS();
  res.json(jwks);
});
 
app.listen(3000, () => {
  console.log('JWKS endpoint running on port 3000');
});

JWT Verification Process

When you send a token to the Custom Auth Login API, KryptoGO:

Extracts the kid (key ID) from the token header
Fetches the JWKS from your specified JWK URL
Locates the key with the matching kid in the JWKS
Verifies the token signature using the public key
Validates that:
- The token is not expired
- The issuer (iss) matches your configured JWT issuer
- The audience (aud) matches your configured JWT audience
Extracts the user ID from the configured UID field
Creates or authenticates the user in the KryptoGO system

Testing Your JWT Setup

Before integrating with production, we recommend testing your JWT implementation:

Generate a sample token using your authentication system
Decode and verify the token using a tool like jwt.io
Check that all required claims (iss, aud, exp, and your UID field) are present
Test with the Custom Auth Login API in a development environment

During the integration process, KryptoGO can help verify your JWT implementation and resolve any issues before going live.

Integration Workflow

Here’s the technical workflow for setting up the JWT authentication integration with KryptoGO:

Setup Your Key Infrastructure
- Generate RSA or ECDSA key pairs for signing tokens
- Assign a unique key ID (kid) to each key
- Create a JWKS endpoint that serves your public keys
Configure Your JWT Generation
- Implement token generation with proper headers (including kid)
- Include required claims in the payload (iss, aud, exp, and your UID field)
- Sign tokens using your private key
Provide Configuration to KryptoGO
- Share your JWKS URL (jwk_url)
- Specify your JWT audience (jwt_audience)
- Specify your JWT issuer (jwt_issuer)
- Indicate which field contains the user ID (jwt_uid_field)
Configuration by KryptoGO
- KryptoGO updates your organization’s JWT verification settings
- KryptoGO provides you with a client ID for API requests
Integration Testing
- Test token generation and verification
- Ensure all required claims are properly included
- Verify JWT headers contain the correct key ID
- Test the end-to-end authentication flow
Production Deployment
- Implement proper key rotation procedures
- Set up monitoring for JWKS endpoint availability
- Establish a process for communicating changes to KryptoGO

⚠️

Key management is critical to security. Implement proper safeguards for your private keys and establish a process for key rotation. Any changes to your keys or JWKS endpoint must be coordinated with KryptoGO to prevent authentication disruptions.

Endpoint


POST https://wallet.kryptogo.app/v1/auth/login/custom

Headers

Name	Type	Required	Description
Content-Type	`string`	Yes	Must be `application/json`

Request Body

Name	Type	Required	Description
client_id	`string`	Yes	Your application’s client ID
token	`string`	Yes	Your user’s authentication token

Response Fields

Field	Type	Description
code	`number`	Status code (0 for success)
data.kg_token	`string`	KryptoGO token for authenticating subsequent requests

Example Request

Node.js


const axios = require('axios');
 
const response = await axios.post(
  'https://wallet.kryptogo.app/v1/auth/login/custom',
  {
    client_id: 'abcd4321abcd',
    token: 'eyj6...'
  },
  {
    headers: { 'Content-Type': 'application/json' }
  }
);

Python


import requests
 
response = requests.post(
    "https://wallet.kryptogo.app/v1/auth/login/custom",
    json={
        "client_id": "abcd4321abcd",
        "token": "eyj6..."
    }
)

Go


import (
    "bytes"
    "encoding/json"
    "net/http"
)
 
data := map[string]string{
    "client_id": "abcd4321abcd",
    "token":     "eyj6...",
}
jsonData, _ := json.Marshal(data)
 
req, _ := http.NewRequest("POST", 
    "https://wallet.kryptogo.app/v1/auth/login/custom",
    bytes.NewBuffer(jsonData))
req.Header.Add("Content-Type", "application/json")
 
resp, _ := http.DefaultClient.Do(req)

Example Response


{
  "code": 0,
  "data": {
    "kg_token": "eyJhb..."
  }
}

Create Payment Intent

Description

Create a new payment intent when a user wants to top up their account or make a purchase using cryptocurrency.

Prerequisites

⚠️

Before using this API, you need:

Client ID - Your application’s client ID
Origin header - Your application’s domain

Endpoint


POST https://wallet.kryptogo.app/v1/payment/intent

Headers

Name	Type	Required	Description
Content-Type	`string`	Yes	Must be `application/json`
Client-Id	`string`	Yes	Your application’s client ID
Origin	`string`	Yes	Your application’s domain

Request Body

Name	Type	Required	Description
fiat_amount	`string`	Yes	The amount in fiat currency (e.g., “300.0”)
fiat_currency	`string`	Yes	The fiat currency code (TWD or USD)
callback_url	`string`	No	URL to receive payment status updates
order_data	`object`	No	Arbitrary data about the order (e.g., order_id, item_id). Will be returned unaltered in callbacks. Max 1000 characters when marshalled.

Response Fields

Field	Type	Description
code	`number`	Status code (0 for success)
data.payment_intent_id	`string`	Unique identifier for the payment intent
data.payment_chain_id	`string`	The blockchain network ID for the payment
data.payment_address	`string`	The wallet address to receive the payment
data.token_address	`string`	The token contract address
data.symbol	`string`	The token symbol (e.g., USDT)
data.decimals	`number`	Number of decimal places for the token
data.crypto_amount	`string`	Amount of cryptocurrency to be paid
data.fiat_amount	`string`	Original fiat amount specified
data.fiat_currency	`string`	Fiat currency code (TWD or USD)
data.payment_deadline	`number`	Unix timestamp for payment expiration
data.status	`string`	Current status: pending, success, or expired

Callback

If you provide a callback_url, your server will receive a POST request when the payment status changes with the following data:

Field	Type	Description
payment_intent_id	`string`	Unique identifier for the payment intent
client_id	`string`	Your application’s client ID
fiat_amount	`string`	Amount in fiat currency
fiat_currency	`string`	Fiat currency code (TWD or USD)
payment_deadline	`number`	Unix timestamp when the payment intent expires
status	`string`	Current status: pending, success, or expired
payment_chain_id	`string`	The blockchain network ID for the payment
symbol	`string`	The token symbol (e.g., USDT)
crypto_amount	`string`	Amount of cryptocurrency paid
order_data	`object`	The order data you provided in the original request
callback_url	`string`	The callback URL (your server endpoint)

Example callback payload:


{
  "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",
  "order_data": {
    "order_id": "uid_12345",
    "item_id": "100"
  },
  "callback_url": "https://example.com/callback"
}

Your server should respond with a 200 status code to acknowledge receipt of the callback.

Example Request

Node.js


const axios = require('axios');
 
const response = await axios.post(
  'https://wallet.kryptogo.app/v1/payment/intent',
  {
    fiat_amount: '300.0',
    fiat_currency: 'TWD',
    callback_url: 'https://example.com/callback',
    order_data: {
      order_id: 'uid_12345',
      item_id: '100',
      customer_id: '0x03971234567890'
    }
  },
  {
    headers: { 
      'Content-Type': 'application/json',
      'Client-Id': 'your-client-id',
      'Origin': 'https://yourdomain.com'
    }
  }
);

Python


import requests
 
response = requests.post(
    "https://wallet.kryptogo.app/v1/payment/intent",
    json={
        "fiat_amount": "300.0",
        "fiat_currency": "TWD",
        "callback_url": "https://example.com/callback",
        "order_data": {
            "order_id": "uid_12345",
            "item_id": "100",
            "customer_id": "0x03971234567890"
        }
    },
    headers={
        "Client-Id": "your-client-id",
        "Origin": "https://yourdomain.com"
    }
)

Go


import (
    "bytes"
    "encoding/json"
    "net/http"
)
 
orderData := map[string]string{
    "order_id": "uid_12345",
    "item_id": "100",
    "customer_id": "0x03971234567890",
}
 
data := map[string]interface{}{
    "fiat_amount": "300.0",
    "fiat_currency": "TWD",
    "callback_url": "https://example.com/callback",
    "order_data": orderData,
}
jsonData, _ := json.Marshal(data)
 
req, _ := http.NewRequest("POST", 
    "https://wallet.kryptogo.app/v1/payment/intent",
    bytes.NewBuffer(jsonData))
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Client-Id", "your-client-id")
req.Header.Add("Origin", "https://yourdomain.com")
 
resp, _ := http.DefaultClient.Do(req)

Example Response


{
  "code": 0,
  "data": {
    "payment_intent_id": "123456789",
    "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,
    "order_data": {
      "order_id": "uid_12345",
      "item_id": "100",
      "customer_id": "0x03971234567890"
    },
    "callback_url": "https://example.com/callback"
  }
}

Get Payment Intent Status

Description

Check the current status of a specific payment intent.

Prerequisites

⚠️

Before using this API, you need:

Client ID - Your application’s client ID
Payment Intent ID - The ID of the payment intent to check

Endpoint


GET https://wallet.kryptogo.app/v1/payment/intent/{id}

Headers

Name	Type	Required	Description
Client-Id	`string`	Yes	Your application’s client ID
Origin	`string`	Yes	Your application’s domain

Path Parameters

Name	Type	Required	Description
id	`string`	Yes	The payment intent ID

Response Fields

Field	Type	Description
code	`number`	Status code (0 for success)
data	`object`	Same structure as the Create Payment Intent response

Example Request

Node.js


const axios = require('axios');
 
const response = await axios.get(
  `https://wallet.kryptogo.app/v1/payment/intent/${paymentIntentId}`,
  {
    headers: { 
      'Client-Id': 'your-client-id',
      'Origin': 'https://yourdomain.com'
    }
  }
);

Python


import requests
 
response = requests.get(
    f"https://wallet.kryptogo.app/v1/payment/intent/{payment_intent_id}",
    headers={
        "Client-Id": "your-client-id",
        "Origin": "https://yourdomain.com"
    }
)

Go


import "net/http"
 
req, _ := http.NewRequest("GET", 
    fmt.Sprintf("https://wallet.kryptogo.app/v1/payment/intent/%s", paymentIntentID),
    nil)
req.Header.Add("Client-Id", "your-client-id")
req.Header.Add("Origin", "https://yourdomain.com")
 
resp, _ := http.DefaultClient.Do(req)

Example Response


{
  "code": 0,
  "data": {
    "payment_intent_id": "123456789",
    "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": "success",
    "payment_tx_hash": "0x1234567890abcdef..."
  }
}

Transfer Tokens (Asset Pro Transfer)

Description

Transfer tokens to a user’s wallet when they want to withdraw funds from your application. This API can be used for game payouts, user withdrawals, or automated rewards distribution.

Use Cases

Game Withdrawals: Allow players to withdraw their in-game earnings to their personal wallets
Automated Payouts: Schedule regular payouts for rewards or earnings
User Withdrawals: Process withdrawal requests from your application’s users

Prerequisites

⚠️

Before using this API, you need:

Organization ID - Contact KryptoGO to get your organization ID if you don’t have one
Studio API Key - Obtained in KryptoGO Studio
Sufficient token balance in your organization’s wallet

Endpoint


POST https://wallet.kryptogo.app/v1/studio/organization/{org_id}/asset/pro/transfer

Headers

Name	Type	Required	Description
X-STUDIO-API-KEY	`string`	Yes	Your Studio API key

Path Parameters

Name	Type	Required	Description
org_id	`string`	Yes	Your organization ID

Request Body

Name	Type	Required	Description
chain_id	`string`	Yes	The blockchain network ID (e.g., “eth”, “arb”)
token_address	`string`	Yes	The token contract address
amount	`string`	Yes	The amount to transfer (in token units, not wei)
to	`string`	Yes	Recipient wallet address
memo	`string`	No	Optional memo for the transfer (useful for tracking purposes)

When specifying token amounts, use the token’s natural units (e.g., “10.5” USDT), not the smallest unit (wei). The API handles the conversion using the token’s decimals.

Response Fields

Field	Type	Description
code	`number`	Status code (0 for success)
data.tx_hash	`string`	Transaction hash of the transfer (can be used to track on block explorers)
data.fee	`string`	Transaction fee amount

Error Codes

Code	Description	Solution
1002	Parameter Incorrect Error	Check your request parameters for errors
4015	Balance not enough	Add more funds to your organization’s wallet
6003	Transfer limit exceeded	Reduce the transfer amount or contact KryptoGO to increase your limit
1013	Internal unknown error	Contact KryptoGO support with the request details
4016	Get balance error	Contact KryptoGO support

Example Request

Node.js


const axios = require('axios');
 
const response = await axios.post(
  `https://wallet.kryptogo.app/v1/studio/organization/${orgId}/asset/pro/transfer`,
  {
    chain_id: "arb",
    token_address: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
    amount: "10.0",
    to: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    memo: "Game withdrawal"
  },
  {
    headers: { 
      'X-STUDIO-API-KEY': apiKey,
      'Content-Type': 'application/json'
    }
  }
);

Python


import requests
 
response = requests.post(
    f"https://wallet.kryptogo.app/v1/studio/organization/{org_id}/asset/pro/transfer",
    json={
        "chain_id": "arb",
        "token_address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
        "amount": "10.0",
        "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "memo": "Game withdrawal"
    },
    headers={
        "X-STUDIO-API-KEY": api_key,
        "Content-Type": "application/json"
    }
)

Go


import (
    "bytes"
    "encoding/json"
    "net/http"
)
 
data := map[string]string{
    "chain_id": "arb",
    "token_address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
    "amount": "10.0",
    "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "memo": "Game withdrawal",
}
jsonData, _ := json.Marshal(data)
 
req, _ := http.NewRequest("POST", 
    fmt.Sprintf("https://wallet.kryptogo.app/v1/studio/organization/%s/asset/pro/transfer", orgID),
    bytes.NewBuffer(jsonData))
req.Header.Add("X-STUDIO-API-KEY", apiKey)
req.Header.Add("Content-Type", "application/json")
 
resp, _ := http.DefaultClient.Do(req)

Error Response Example


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

Example Success Response


{
  "code": 0,
  "data": {
    "tx_hash": "0x1234567890abcdef...",
    "fee": "0.00021"
  }
}

List all payment intents of your organization

Description

Get all payment intents for your organization.

Prerequisites

⚠️

Before using this API, you need:

Organization ID - Contact KryptoGO to get your organization ID
Studio API Key - Contact KryptoGO to get your API key

Endpoint


GET https://wallet.kryptogo.app/v1/studio/organization/{org_id}/payment/intents

Headers

Name	Type	Required	Description
X-STUDIO-API-KEY	`string`	Yes	Your Studio API key

Path Parameters

Name	Type	Required	Description
org_id	`number`	Yes	Your organization ID

Query Parameters

Name	Type	Required	Description
status	`string`	No	Filter by status: `pending`, `success`, or `expired`
client_id	`string`	No	Filter by client ID
page_number	`number`	No	Page number for pagination
page_size	`number`	No	Number of items per page

Response Fields

Field	Type	Description
payment_intent_id	`string`	Unique identifier for the payment intent
payment_chain_id	`string`	The payment chain ID where customer should send tokens on
payment_address	`string`	The wallet address where customer should send tokens to
token_address	`string`	The smart contract address of the token being used for payment
symbol	`string`	The token symbol (e.g., USDT, USDC)
decimals	`number`	Number of decimal places for the token (e.g., 6 for USDT)
crypto_amount	`string`	Amount of crypto tokens to be paid
fiat_amount	`string`	Original fiat amount in the specified currency
fiat_currency	`string`	Fiat currency code (TWD or USD)
payment_deadline	`number`	Unix timestamp when the payment intent expires
status	`string`	Current status: pending (awaiting payment), success (paid), or expired
payment_tx_hash	`string`	User’s transaction hash after successful payment, null if pending/expired

Example Request

Node.js


const axios = require('axios');
 
const response = await axios.get(
  `https://wallet.kryptogo.app/v1/studio/organization/${orgId}/payment/intents`,
  {
    headers: { 'X-STUDIO-API-KEY': apiKey },
    params: { status: 'pending' }
  }
);

Python


import requests
 
response = requests.get(
    f"https://wallet.kryptogo.app/v1/studio/organization/{org_id}/payment/intents",
    headers={"X-STUDIO-API-KEY": api_key},
    params={"status": "pending"}
)

Go


import "net/http"
 
req, _ := http.NewRequest("GET", 
    fmt.Sprintf("https://wallet.kryptogo.app/v1/studio/organization/%d/payment/intents", orgID),
    nil)
req.Header.Add("X-STUDIO-API-KEY", apiKey)
 
resp, _ := http.DefaultClient.Do(req)

Example Response


{
  "code": 0,
  "paging": {
    "page_number": 1,
    "page_size": 10,
    "total": 1
  },
  "data": [
    {
      "payment_chain_id": "arb",
      "payment_intent_id": "123456789",
      "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
    }
  ]
}