Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.yativo.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through setting up the Yativo Crypto Payment Gateway to accept payments. By the end, you’ll have a working payment flow: submit a compliance application, create a payment intent, share a link, and receive crypto settled to your Gateway Account.
1

Authenticate

Get a Bearer token using your API key:
curl -X POST 'https://crypto-api.yativo.com/api/v1/auth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "yativo_...",
    "api_secret": "..."
  }'
Response
{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOi...",
    "token_type": "Bearer",
    "expires_in": 86400
  }
}
2

Submit a Gateway Application (one-time)

Before creating payment links you must pass a one-time compliance check. Attempting to skip this returns 403 GATEWAY_APPLICATION_REQUIRED.
curl -X POST 'https://crypto-api.yativo.com/api/v1/crypto-gateway/apply' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "logo_url": "https://yoursite.com/logo.png",
    "support_email": "support@yoursite.com",
    "social_media_url": "https://twitter.com/yourcompany",
    "business_type": "ecommerce",
    "expected_volume": "1k_10k",
    "website_url": "https://yoursite.com",
    "webhook_url": "https://yoursite.com/webhooks/yativo"
  }'
Poll GET /crypto-gateway/application to check approval status. Approval typically takes under 24 hours.
3

Create a payment intent

Once approved, create a payment intent specifying the amount, a title (shown on the checkout page), and the tokens you accept:
curl -X POST 'https://crypto-api.yativo.com/api/v1/crypto-gateway/payments' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Pro Plan — Monthly",
    "description": "1-month access to Pro features",
    "requested_amount": 49.99,
    "accepted_assets": ["USDC_SOL", "USDT_POL", "USDC_BASE"],
    "external_reference": "order_abc123"
  }'
Response
{
  "success": true,
  "data": {
    "payment_id": "pay_a1b2c3d4e5f6",
    "title": "Pro Plan — Monthly",
    "description": "1-month access to Pro features",
    "requested_amount": 49.99,
    "status": "awaiting_payment",
    "checkout_url": "https://crypto-checkout.yativo.com/pay/pay_a1b2c3d4e5f6",
    "embed_url": "https://crypto-checkout.yativo.com/embed/pay_a1b2c3d4e5f6",
    "accepted_options": [
      { "asset_code": "USDC_SOL", "network": "solana",  "deposit_address": "7xKXtg..." },
      { "asset_code": "USDT_POL", "network": "polygon", "deposit_address": "0xAbCd..." },
      { "asset_code": "USDC_BASE", "network": "base",   "deposit_address": "0x1234..." }
    ],
    "external_reference": "order_abc123",
    "payment_window_expires_at": "2026-04-18T13:00:00Z",
    "monitoring_ends_at": "2026-04-18T13:20:00Z",
    "created_at": "2026-04-18T12:00:00Z"
  }
}
Redirect your customer to the checkout_url.
4

Share the checkout link

Redirect your customer to the checkout_url, or embed it in:
  • An email invoice
  • A QR code
  • A “Pay with Crypto” button on your site
  • A Telegram/Discord bot message
The hosted checkout page collects the customer’s email, displays the title and description, lets the customer choose a token, shows the deposit address and QR code, and auto-confirms once the on-chain payment lands.
5

Listen for webhook

Register a webhook to get notified when the payment settles. The webhook_url from your application is used automatically; you can also override it per payment.
Webhook Payload — gateway.payment.settled
{
  "event": "gateway.payment.settled",
  "data": {
    "payment_id": "pay_a1b2c3d4e5f6",
    "title": "Pro Plan — Monthly",
    "requested_amount": 49.99,
    "settled_amount": 49.99,
    "asset_code": "USDC_SOL",
    "network": "solana",
    "transaction_hash": "5UxR7Kq...",
    "status": "paid",
    "external_reference": "order_abc123",
    "late_payment": false,
    "settled_at": "2026-04-18T12:08:00Z"
  }
}
6

Verify and fulfill

When your webhook endpoint receives the gateway.payment.settled event, check status === "paid" or "paid_late" and fulfill the order using your external_reference:
app.post('/webhooks/yativo', (req, res) => {
  const { event, data } = req.body;

  if (event === 'gateway.payment.settled') {
    const { payment_id, status, external_reference } = data;
    if (status === 'paid' || status === 'paid_late') {
      fulfillOrder(external_reference);
    }
  }

  res.status(200).send('ok');
});

​
Payment Status Values

StatusDescription
awaiting_paymentWaiting for the customer to send funds
monitoring_late_windowPrimary window closed; still accepted in grace period
paidConfirmed on-chain within the primary window
paid_lateConfirmed during the late monitoring window
expiredMonitoring window closed with no payment detected
cancelledCancelled by the merchant

​
Full Example (TypeScript)

import { YativoCrypto } from '@yativo/crypto-sdk';

const client = new YativoCrypto({
  apiKey: process.env.YATIVO_API_KEY!,
  apiSecret: process.env.YATIVO_API_SECRET!,
});

// Create a payment for a customer's order
async function createPayment(orderId: string, amount: number) {
  const payment = await client.gateway.createPayment({
    title: `Order #${orderId}`,
    description: 'Your purchase from Acme Store',
    requestedAmount: amount,
    acceptedAssets: ['USDC_SOL', 'USDT_POL', 'USDC_BASE'],
    externalReference: orderId,
  });

  return payment.checkoutUrl; // Send this to your customer
}

​
Next Steps

Payment Gateway

Full Payment Gateway documentation — analytics, reconciliation, and more.

Webhook Integration

Set up and verify webhooks.