Create Widget Session

The widget sessions endpoint creates a session that allows users to complete their cryptocurrency purchase through our secure payment widget. After creating a session, redirect users to the provided widget URL. Create a session for users to complete their cryptocurrency purchase through our widget.

Important Testnet Limitation: The testnet environment currently supports only USDC, USDT, MATIC on Polygon network. Do not attempt to initiate transactions with other tokens or on other blockchain networks as they will fail. Always use:

tokenAddress: USDC, USDT, MATIC
chainId: polygon or 80002 (Polygon Amoy testnet)

Request Headers

Content-Type: application/json
X-API-Key: your_api_key_here
X-Request-Signature: hmac_sha256_signature

X-Request-Signature Header: This header is required for all widget session creation requests. See the X-Request-Signature Authentication section below for detailed signature generation instructions.

Request Body

{
    "fiatAmount": 15,
    "fiatCurrency": "EUR",
    "cryptoCurrency": "USDC",
    "network": "polygon",
    "destinationAddress": "0x977BC1915dA4f7edA9D2e49BC08356db37478538",
    "email": "[email protected]",
    "paymentMethod": "google_pay",
    "unlockedFields": ["fiatAmount", "destinationAddress"],
    "metadata": {
        "yourfield": "loremipsum",
        "someotherfield": 1234,
        "_externalPartnerId": "partnerId123"
    },
    "successUrl": "https://yoursite.com/success",
    "failureUrl": "https://yoursite.com/failure",
    "ipAddress": "127.0.0.1"
}

Request Parameters

Parameter	Type	Required	Description
`fiatAmount`	number	Yes*	Amount in fiat currency
`cryptoAmount`	number	Yes*	Amount in cryptocurrency
`fiatCurrency`	string	Yes	Fiat currency code (USD, EUR)
`cryptoCurrency`	string	Yes	Cryptocurrency symbol
`network`	string	Yes	Blockchain network name
`destinationAddress`	string	Yes	Wallet address to receive crypto
`email`	string	No	User’s email address
`paymentMethod`	string	No	Payment method
`unlockedFields`	array	No	Fields that will be available to be changed in the widget (see available fields below)
`metadata`	object	No	Additional information for the transaction that you would like to receive in webhook (see metadata below)
`successUrl`	string	No	URL to redirect on successful payment
`failureUrl`	string	No	URL to redirect on failed payment
`ipAddress`	string	No	IP address of the user

Conversion Type

use fiatAmount to create a widget based on amount you want to spend on crypto tokens
use cryptoAmount to create a widget based on crypto tokens you want to buy.

Providing both will result in an error.

Payment Methods

There are several payment methods available for various countries and currencies. Verify available methods using the fiat currencies endpoint

Payment method	Testnet	Production
`card`	Yes	Yes
`bank_transfer`	Yes	Yes
`apple_pay`	No	Yes
`google_pay`	No	Yes
`astropay`	No	Yes
`blik`	No	Yes
`ideal`	No	Yes

IP Address

Value: Can be in IPv4 dotted decimal (192.0.2.1), IPv6 (2001:db8::68), or IPv4-mapped IPv6 (::ffff:192.0.2.1) form.Purpose: Include the end user’s public IP address with requests to strengthen fraud prevention, identity verification, and session integrity checks.Behavior: Providing the correct End-User IP is essential for a seamless checkout experience. If this field is missing or cannot be verified, additional checks or restrictions may apply. This can lead to extra verification steps, reduced limits, or delayed processing.

Metadata

Collection of property/value pairs.Properties: Additional information for the transaction that you would like to receive in webhookReserved properties (prefixed with _):

_externalPartnerId(string): Identifier for external partner attribution

"metadata": {
    "yourfield": "loremipsum",
    "someotherfield": 1234,
    "_externalPartnerId": "partnerId123"
}

X-Request-Signature Authentication

All widget creation requests require HMAC-SHA256 signature validation for enhanced security. You must include the X-Request-Signature header with every request to the widget sessions endpoint. How to generate the signature:

Serialize your request payload to JSON
Convert to UTF-8 bytes
Compute HMAC-SHA256 using your partner’s signature secret
Encode the result as a hexadecimal string
Include in the X-Request-Signature header

Example signature generation (JavaScript):

const crypto = require('crypto');

function generateSignature(payload, signatureSecret) {
  // 1. Serialize to JSON
  const jsonString = JSON.stringify(payload);
  
  // 2. Convert to UTF-8 bytes
  const utf8Bytes = Buffer.from(jsonString, 'utf8');
  
  // 3. Compute HMAC-SHA256
  const hmac = crypto.createHmac('sha256', signatureSecret);
  hmac.update(utf8Bytes);
  
  // 4. Encode as hexadecimal
  const signature = hmac.digest('hex');
  
  return signature;
}

// Usage
const payload = {
  fiatAmount: 15,
  fiatCurrency: 'EUR',
  cryptoCurrency: 'USDC',
  network: 'polygon',
  destinationAddress: '0x977BC1915dA4f7edA9D2e49BC08356db37478538'
};

const signature = generateSignature(payload, 'your_signature_secret');
console.log(signature); // Use this in X-Request-Signature header

Error response:

The X-Request-Signature header is required for all widget session creation requests. Requests without a valid signature will be rejected with a 401 Unauthorized response, as shown below.

{
  "code": "UNAUTHORIZED",
  "message": "Unauthorized request"
}

Available Unlocked Fields

The unlockedFields parameter controls which passed params are available for change in the widget. Only the following fields can be included in this array:

Field Name	Description
`fiatAmount`	Amount in source currency
`cryptoAmount`	Amount in target cryptocurrency
`fiatCurrency`	Source fiat currency
`email`	User’s email address
`network`	Blockchain network name
`paymentMethod`	Payment method type
`successUrl`	Success redirect URL
`failureUrl`	Failure redirect URL

Fields not included in unlockedFields will be encrypted and hidden from view in the widget.This feature is not available for the general audience at the moment. Using this parameter will not change the widget behavior.

Response

{
  "sessionId": "7c303babX3jp7c4942904a262a0c1b94",
  "widgetUrl": "https://buy.kryptonim.com/exchange?gdata=MWXEGqPRPfprP2WtH9edvlhNnBwyRWVpVXiJIJbPQtIgcWxGfSvjoEJxf7YgHnKKMcQ8RdXUaP0tmXnReQ7VoY%2FVvHNctK7KrIdPJ6h6lW3MV1y%2BSXS%2BNWqJFJlIWQJ23JpqPNbh23PJ%2FBjuYTcyvzUgsd3i%2BChohw%2F9JB6EC9pR9LTUK87WOwOQlcnGh04s8n9xVWs9ZKeWHyC5fjV7v%2BNyDQNiNfTwScmps9pHsQ4%2FrQZkHpQwTKw7IgQ53TrbNIq7q4CfnpVjx1mZAyJAKfs3wEJAAXFsh6dC2DbbWF83F8kN1%2B2nMF8%2B%2BQwYuIwneRRj%2BOYhWtTbqUpV%2F7cmMxswnD7yESOuC7zrJGEdWdZKNUF9Y3iPOo50L2EkLmAGe6amRPDUUFa6qWIWpcWBMy2EPy%2FfV1IjqOWCqvV2HQPeo46MR5r%2FA3PlpoquzKzIcSIcX8W%2BXvLb6hz1ivHmxJhYXlrWg6Ws6aZg6z1upA94UGVGi1QxTOpcX1ADMTM1ky3oTlsOHUjqFMxhuEsKqThG5X02mgZ%2F%2FPRr1AtNaNNUiCQGOcxUj0X6%2FaKievFK%2BbGycFiQYaCS9QmVbcLIdwCNy6hB1ZQ43jbc8c9c9OzZo2%2Bya24ICLpAhX3qnGLPWtmb%2B4tPcr8OaS1rMStBt0LhIrPpHat9zyC6lgbA7OgaMZAApJsgvIsjHq%2BYnJOWUsuX3OjzSfJ%2BQ7Vt19a3VZeACb9enVBJZLziozPe2k0UrYz620aWo8BWOf8y%2B7FYTuTRcjYd%2B75e%2Bo86bozuvWQ%2BViQ02BwC%2BI6E1ZCAZnGJrUODCAIbGfPXzAiOvEcTpa0nPe3PKWqu%2FJlx1Coim3wdE87tSbee0fTH2kAcfcZrXJWKh%2BKO2qC981Yr4fFg6%2FsdZowKJiActzHHHgQ0fiu%2FcFn5qxZsBfhMDDxIIdGQgYBB6WsLJKV8KYLDz7mJBQZOJBFv2tgQCSFoo7TYmOlhnfxEFZ3EbGlSKZ1MAKK7HQKlI9M3A7jrG82mubGkat0q4fvHsJyvRufUiQj5sD96J3tGo%2BUAxJPuSG71SnGdpg%2FSuhYxlwf%2FfAl8LhMgB22I07tF%2BN5tlAiQ3GzKzj27K2vZ%2FHsNXPzDgIGWSOifby5STQiRnZ%2F6ZcJ%2Br1h6%2Bbh1rzPzuBMh2%2BASAiYC9TT2ecKovr2CAOerv62cpLCJVTpu4W7Ud9Zpa2vJFSRyS53obL%2FZmfIMoFc20swzsFLH%2BggVYFxeaWgeRVeU%2BL1xQLAs5MqKfHwPbFDQsiA%2Fc92TrjAqAYyp10nibq2C5YztlKh1f76FNl%2FlUC6XOGZ0Ghy8IMjyNNX%2Bzi5hPWCbQj%2BV%2BqV9sKAK5s5I38UBOw%3D%3D&m=XxxXXx0&address=0x977BC1915dA4f7edA9D2e49BC08356db37478538",
  "expiresAt": "2025-11-13T08:18:47.447527Z"
}

Response Fields

Field	Type	Description
`sessionId`	string	Unique session identifier, used as a transaction id later on
`widgetUrl`	string	URL to redirect users to
`expiresAt`	string	Session expiration timestamp (UTC timezone)

Sessions expire after 30 minutes. Make sure to redirect users promptly after creating a session.

Integration Examples

requestExample.js

const crypto = require('crypto');

// Function to generate HMAC-SHA256 signature
function generateSignature(payload, signatureSecret) {
  const jsonString = JSON.stringify(payload);
  const utf8Bytes = Buffer.from(jsonString, 'utf8');
  const hmac = crypto.createHmac('sha256', signatureSecret);
  hmac.update(utf8Bytes);
  return hmac.digest('hex');
}

const payload = {
    fiatAmount: 15,
    fiatCurrency: 'EUR',
    cryptoCurrency: 'USDC',
    network: 'polygon',
    destinationAddress: '0x977BC1915dA4f7edA9D2e49BC08356db37478538',
    email: '[email protected]',
    paymentMethod: 'google_pay',
    unlockedFields: ['fiatAmount', 'destinationAddress'],
    metadata: {
        yourfield: 'loremipsum',
        someotherfield: 1234
    },
    successUrl: 'https://yoursite.com/success',
    failureUrl: 'https://yoursite.com/failure'
};

// Generate signature
const signature = generateSignature(payload, 'your_signature_secret');

const response = await axios.post('{{base_url}}/v1/widget-sessions', payload, {
    headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'your_api_key_here',
        'X-Request-Signature': signature
    }
});

// Redirect user to widget
window.location.href = response.data.widgetUrl;

1. Full Page Redirect

Redirect users to the widget URL in the current window:

window.location.href = session.widgetUrl;

2. New Window/Tab

Open the widget in a new window or tab:

window.open(session.widgetUrl, '_blank');

Handling Redirects

After users complete or cancel their transaction, they’ll be redirected based on your configuration:

Success Redirect

Users are redirected to successUrl with query parameters:

https://yoursite.com/success?sessionId=7c303babX3jp7c4942904a262a0c1b94&status=completed

Failure Redirect

Users are redirected to failureUrl if the payment fails or is cancelled:

https://yoursite.com/failure?sessionId=7c303babX3jp7c4942904a262a0c1b94&status=failed

Using Metadata

The metadata field allows you to store additional information with the session:

{
  "metadata": {
    "orderId": "12345",
    "userId": "user-789",
    "productName": "Premium Subscription",
    "tier": "gold"
  }
}

This metadata will be:

Included in webhook notifications
Useful for reconciliation and tracking

Error Responses

Unsupported Network

{
    "code": "INVALID_REQUEST",
    "message": "Unsupported network"
}

Signature Validation Errors

The following error may occur if signature validation fails:

Unauthorized Request

{
    "code": "UNAUTHORIZED",
    "message": "Unauthorized request"
}

If you receive signature validation errors, ensure that:

The X-Request-Signature header is included in all requests
The signature is generated using the correct signature secret
The request payload is serialized to JSON before signing
The signature is encoded as a hexadecimal string
The exact same payload is used for signature generation and the request body

Possible Signature Issues

Issue 1: “Unauthorized request” after deployment

Cause: Signature secret not configured in production Solution:

Verify SIGNATURE_SECRET environment variable is set
Check that it matches the value received from Kryptonim
Restart your application after setting the variable

Issue 2: Signature validation fails intermittently

Cause: JSON formatting differences between signature generation and request Solution:

Ensure you’re using the same JSON serialization for both signature and request
Use consistent separators (e.g., separators=(',', ':') in Python)
Avoid extra whitespace or formatting differences

Issue 3: Works in development, fails in production

Cause: Different signature secret in production environment Solution:

Verify production environment variables are correctly set
Check that you’re not using development credentials in production
Ensure secrets are properly loaded in production environment

Security Best Practices

Minimize unlocked fields: Only include essential fields in unlockedFields to maintain security
Validate wallet addresses before creating sessions
Store the sessionId for tracking and reconciliation
Set up webhooks to receive real-time updates
Handle expired sessions gracefully
Test the full flow in development before going live
Use HTTPS for all redirect URLs to ensure secure communication
Always include signature: The X-Request-Signature header is required for all widget session creation requests
Protect signature secrets: Never expose your signature secret in client-side code or public repositories
Validate signatures: Always verify signature generation matches the expected format

Always verify that the destination address belongs to your user before creating a session. This helps prevent fraud and ensures funds are sent to the correct wallet.

Getting started

POST /v1/widget-sessions

Request Headers

Request Body

Request Parameters

Conversion Type

Payment Methods

IP Address

Metadata

X-Request-Signature Authentication

Available Unlocked Fields

Response

Response Fields

Integration Examples

Widget Integration Options

1. Full Page Redirect

2. New Window/Tab

Handling Redirects

Success Redirect

Failure Redirect

Using Metadata

Error Responses

Unsupported Network

Signature Validation Errors

Unauthorized Request

Possible Signature Issues

Issue 1: “Unauthorized request” after deployment

Issue 2: Signature validation fails intermittently

Issue 3: Works in development, fails in production

Security Best Practices

Getting started

​POST /v1/widget-sessions

​Request Headers

​Request Body

​Request Parameters

​Conversion Type

​Payment Methods

​IP Address

​Metadata

​X-Request-Signature Authentication

​Available Unlocked Fields

​Response

​Response Fields

​Integration Examples

​Widget Integration Options

​1. Full Page Redirect

​2. New Window/Tab

​Handling Redirects

​Success Redirect

​Failure Redirect

​Using Metadata

​Error Responses

​Unsupported Network

​Signature Validation Errors

​Unauthorized Request

​Possible Signature Issues

​Issue 1: “Unauthorized request” after deployment

​Issue 2: Signature validation fails intermittently

​Issue 3: Works in development, fails in production

​Security Best Practices

POST /v1/widget-sessions

Request Headers

Request Body

Request Parameters

Conversion Type

Payment Methods

IP Address

Metadata

X-Request-Signature Authentication

Available Unlocked Fields

Response

Response Fields

Integration Examples

Widget Integration Options

1. Full Page Redirect

2. New Window/Tab

Handling Redirects

Success Redirect

Failure Redirect

Using Metadata

Error Responses

Unsupported Network

Signature Validation Errors

Unauthorized Request

Possible Signature Issues

Issue 1: “Unauthorized request” after deployment

Issue 2: Signature validation fails intermittently

Issue 3: Works in development, fails in production

Security Best Practices