Skip to main content
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.