> ## 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.

# Payment Gateway

> Accept stablecoin payments on 9 chains — hosted checkout or pure API, with built-in compliance gating, underpayment reconciliation, and direct wallet settlement

The Crypto Payment Gateway lets you accept USDC and USDT on any supported chain. Use the **hosted checkout** (share a link, no frontend work) or the **API** to embed payments directly into your flow. Funds settle into a dedicated **Gateway Account** that Yativo creates and manages for you — withdraw manually or enable [Auto-Forwarding](/yativo-crypto/auto-forwarding) for automatic payouts.

***

## How It Works

<Steps>
  <Step title="Submit a Gateway Application">
    Before creating payment links, submit a one-time compliance application via `POST /crypto-gateway/apply`. Provide your business type, expected volume, logo, support email, and social media URL. Yativo reviews and approves your account — this typically takes under 24 hours.
  </Step>

  <Step title="Create a payment link">
    Call `POST /crypto-gateway/payments` with the amount, title, accepted assets, and an optional description of what the customer is paying for. Your logo, support email, and webhook URL are pulled automatically from your approved application.
  </Step>

  <Step title="Customer enters their email and chooses how to pay">
    On the hosted checkout page, the customer first provides their email (used for the on-chain receipt). They then pick from your enabled payment methods and get a deposit address and QR code.
  </Step>

  <Step title="Payment is detected on-chain">
    Yativo monitors the deposit address. Once confirmed on-chain the payment moves to `paid` and the checkout page auto-refreshes.
  </Step>

  <Step title="Funds settle to your Gateway Account">
    The net amount (after fees) is credited to your **Gateway Account** — a dedicated Yativo wallet Yativo creates for you. The relevant token wallet is auto-provisioned when you first create a payment intent for that asset. A webhook fires so your backend can fulfil the order.
  </Step>
</Steps>

***

## Key Features

<CardGroup cols={2}>
  <Card title="Hosted Checkout" icon="browser">
    Share a URL — no frontend code required. The checkout page collects the customer's email, handles asset selection, shows the description of what they're paying for, and auto-confirms once the on-chain payment lands.
  </Card>

  <Card title="API-first" icon="code">
    Fully programmable. Create links, poll status, and receive webhooks from your backend or SDK integration.
  </Card>

  <Card title="Multi-asset acceptance" icon="layer-group">
    Accept USDC and USDT on 9 chains in a single payment link. Customers only see the options you enable.
  </Card>

  <Card title="Gateway Account settlement" icon="bolt">
    Funds settle into a dedicated Gateway Account automatically provisioned for each merchant. Wallets for each accepted token are created automatically on your first payment intent for that asset.
  </Card>

  <Card title="Underpayment Reconciliation" icon="arrows-rotate">
    If a customer sends less than required, they can file an underpayment report from the expired checkout page. You verify the on-chain balance and choose to reverse, reconcile, or settle at the paid amount.
  </Card>

  <Card title="Analytics" icon="chart-bar">
    Track settlement rates, late payments, expired links, preferred tokens, and average checkout-to-confirmed timing — per-merchant and platform-wide.
  </Card>
</CardGroup>

***

## Compliance Gate

Before your first payment link, you must submit a Gateway Application. This is a one-time step.

```bash theme={null}
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"
  }'
```

| Field              | Required | Description                                                                                    |
| ------------------ | -------- | ---------------------------------------------------------------------------------------------- |
| `logo_url`         | Yes      | HTTPS URL to your brand logo — shown on all checkout pages                                     |
| `support_email`    | Yes      | Customer-facing support email — included in expired checkout links                             |
| `social_media_url` | Yes      | Company social media URL for identity verification                                             |
| `business_type`    | Yes      | One of: `ecommerce` `saas` `marketplace` `freelance` `ngo` `gaming` `travel` `finance` `other` |
| `expected_volume`  | Yes      | One of: `under_1k` `1k_10k` `10k_50k` `50k_250k` `over_250k`                                   |
| `website_url`      | No       | Your business website                                                                          |
| `webhook_url`      | No       | Default webhook for all payment events                                                         |

Once submitted, your application enters `pending` status. Attempting to create payment links before approval returns a `403` with `error_code: GATEWAY_APPLICATION_REQUIRED`.

```bash theme={null}
# Check your application status
curl 'https://crypto-api.yativo.com/api/v1/crypto-gateway/application' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

***

## Supported Payment Assets

| `asset_code` | Token | Network   | Standard |
| ------------ | ----- | --------- | -------- |
| `USDC_SOL`   | USDC  | Solana    | SPL      |
| `USDT_SOL`   | USDT  | Solana    | SPL      |
| `USDC_POL`   | USDC  | Polygon   | ERC-20   |
| `USDT_POL`   | USDT  | Polygon   | ERC-20   |
| `USDC_BASE`  | USDC  | Base      | ERC-20   |
| `USDT_BASE`  | USDT  | Base      | ERC-20   |
| `USDC_ARB`   | USDC  | Arbitrum  | ERC-20   |
| `USDT_ARB`   | USDT  | Arbitrum  | ERC-20   |
| `USDC_OP`    | USDC  | Optimism  | ERC-20   |
| `USDT_OP`    | USDT  | Optimism  | ERC-20   |
| `USDC_AVAX`  | USDC  | Avalanche | ERC-20   |
| `USDT_AVAX`  | USDT  | Avalanche | ERC-20   |
| `USDT_TRON`  | USDT  | TRON      | TRC-20   |

<Note>USDC on TRON is not supported — Circle deprecated it. Use `USDT_TRON` instead.</Note>

***

## Create a Payment Link

```bash theme={null}
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": "Invoice #1234",
    "description": "Pro Plan subscription — April 2026",
    "requested_amount": 49.99,
    "accepted_assets": ["USDC_SOL", "USDT_POL", "USDC_BASE"],
    "customer_email": "alice@example.com",
    "external_reference": "order_abc123"
  }'
```

<Note>
  `logo_url`, `support_email`, and `webhook_url` are **not** passed here — they are read automatically from your approved Gateway Application.
</Note>

| Field                    | Required | Description                                                                                       |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------- |
| `title`                  | Yes      | Displayed as the payment title on the checkout page                                               |
| `requested_amount`       | Yes      | Amount in USD (USDC/USDT = 1:1 with USD)                                                          |
| `accepted_assets`        | Yes\*    | Array of `asset_code` values — customer picks one                                                 |
| `asset_code` + `network` | Yes\*    | Legacy single-asset format — use `accepted_assets` instead                                        |
| `description`            | No       | Description of the goods or service — shown on checkout and on the receipt email (max 1000 chars) |
| `customer_email`         | No       | Pre-fills the email field on checkout; skips the email collection step                            |
| `external_reference`     | No       | Your own order ID — echoed back on webhooks                                                       |

\*One of `accepted_assets` or `asset_code` + `network` is required.

```json Response theme={null}
{
  "success": true,
  "data": {
    "payment_id": "pay_a1b2c3d4e5f6",
    "title": "Invoice #1234",
    "description": "Pro Plan subscription — April 2026",
    "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..." }
    ],
    "payment_window_expires_at": "2026-04-18T13:00:00Z",
    "monitoring_ends_at": "2026-04-18T13:20:00Z"
  }
}
```

Share the `checkout_url` with your customer. Each option has its own pre-provisioned deposit address.

***

## Hosted Checkout Flow

The checkout page at `checkout_url`:

1. If multiple assets are accepted, the customer picks one
2. The customer enters their email (skipped if `customer_email` was passed at creation)
3. The payment title and description (if set) are displayed
4. The deposit address and QR code are revealed
5. The customer sends the **exact** asset, on the **exact** network, for the **exact** amount shown
6. The page polls for status and auto-transitions to a success screen once detected on-chain

If the payment window expires before funds arrive, the customer sees an expired state with a "I already sent crypto — report it" button that opens the [underpayment report form](#underpayment-reconciliation).

***

## Gateway Account & Settlement

When you create your first payment intent, Yativo automatically creates a **Gateway Account** for you. All settlement wallets for your payment intents live inside this account — one wallet per accepted token (e.g. a `USDC_SOL` wallet, a `USDT_POL` wallet, etc.).

<Note>
  Gateway Accounts are automatically provisioned by the platform. You cannot create a manual account named "gateway" — that name is reserved. All gateway settlement is tracked separately from your regular Yativo wallets for clean accounting and audit.
</Note>

**Settlement flow:**

1. Customer pays on-chain → deposit received at a platform pool wallet
2. Platform verifies the on-chain transaction amount
3. Net amount (after fees) is credited to your Gateway Account wallet for that token
4. Webhook fires: `gateway.payment.settled`
5. If [Auto-Forwarding](/yativo-crypto/auto-forwarding) is configured on that wallet, funds sweep to your external address automatically

**Settlement rules:**

| Scenario                                        | Outcome                                       |
| ----------------------------------------------- | --------------------------------------------- |
| Exact or over-payment within the primary window | `paid` — credited in full                     |
| Payment arrives in the late monitoring window   | `paid_late` — same credit rules               |
| Underpayment (received \< requested)            | Settlement rejected — use reconciliation flow |
| Payment arrives after monitoring window         | Rejected unless admin force-settles           |

***

## Underpayment Reconciliation

If a customer paid but the amount was short and the window expired, both sides can resolve it without a support ticket.

### Customer side

On the expired checkout, the customer clicks **"I already sent crypto — report it"** and submits their sending wallet address, how much they sent, and an optional note.

```bash theme={null}
# Public endpoint — no auth required
curl -X POST 'https://crypto-api.yativo.com/api/v1/crypto-gateway/pay/pay_a1b2c3d4e5f6/report-underpayment' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_sending_wallet": "7xKXtgMK...",
    "reported_amount": 45.00,
    "customer_email": "alice@example.com",
    "customer_note": "I accidentally sent USDT instead of USDC."
  }'
```

### Merchant side

```bash theme={null}
# List reports
GET /crypto-gateway/reconciliation?status=pending

# Verify the on-chain balance at the gateway wallet
POST /crypto-gateway/reconciliation/:reportId/verify

# Escalate wrong-token or wrong-network cases to Yativo ops
POST /crypto-gateway/reconciliation/:reportId/escalate-recovery

# Reverse: queue a refund (verified amount minus admin-configured fee)
POST /crypto-gateway/reconciliation/:reportId/reverse

# Reconcile: create a new payment link for the shortfall
POST /crypto-gateway/reconciliation/:reportId/reconcile

# Settle as paid: revise original requested amount to verified amount and settle
POST /crypto-gateway/reconciliation/:reportId/settle-as-paid
```

| Status             | Description                                               |
| ------------------ | --------------------------------------------------------- |
| `pending`          | Submitted by customer — awaiting merchant verification    |
| `verified`         | On-chain balance confirmed — merchant chooses next action |
| `reversing`        | Refund queued — ops processing the on-chain transfer      |
| `reversed`         | Refund sent on-chain                                      |
| `reconciled`       | Reconciliatory payment intent created                     |
| `settled_adjusted` | Original intent settled at revised requested amount       |
| `dismissed`        | Dismissed by merchant or admin                            |

***

## Check Payment Status

This endpoint is **public** — no auth required.

```bash theme={null}
curl 'https://crypto-api.yativo.com/api/v1/crypto-gateway/pay/pay_a1b2c3d4e5f6/status'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "payment_id": "pay_a1b2c3d4e5f6",
    "status": "paid",
    "requested_amount": 49.99,
    "settled_amount": 49.99,
    "asset_code": "USDC_SOL",
    "network": "solana",
    "transaction_hash": "5K3p...",
    "late_payment": false,
    "payment_window_expires_at": "2026-04-18T13:00:00Z"
  }
}
```

***

## Payment Statuses

| Status                   | Description                                                    |
| ------------------------ | -------------------------------------------------------------- |
| `awaiting_payment`       | Link created — waiting for the customer to send funds          |
| `monitoring_late_window` | Primary window closed; still accepted for a short grace period |
| `paid`                   | Confirmed on-chain within the primary window                   |
| `paid_late`              | Confirmed in the late monitoring window                        |
| `expired`                | Monitoring window closed with no full payment detected         |
| `cancelled`              | Cancelled by the merchant                                      |

***

## List Payments

```bash theme={null}
curl 'https://crypto-api.yativo.com/api/v1/crypto-gateway/payments' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Returns the 10 most recent payment intents with status, amounts, accepted options, settlement info, and any reconciliation details.

***

## Gateway Overview

```bash theme={null}
curl 'https://crypto-api.yativo.com/api/v1/crypto-gateway/overview' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Returns totals for pending, paid, and paid-late payments, plus your Gateway Account wallet balance for each settled asset.

***

## Analytics

Track payment performance metrics for your gateway. Useful for understanding customer behaviour, tuning monitoring windows, and measuring settlement health.

```bash theme={null}
curl 'https://crypto-api.yativo.com/api/v1/crypto-gateway/analytics/me' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "payment_intents_created": 142,
    "payments_settled": 128,
    "payments_late": 9,
    "payments_expired": 5,
    "customer_claimed_paid_clicks": 130,
    "late_rate_pct": 7.0,
    "expired_rate_pct": 3.5,
    "total_volume_usd": 6384.50,
    "avg_seconds_window_to_settled": 210.0,
    "avg_seconds_claimed_to_settled": 180.0,
    "avg_seconds_late_by": 95.0,
    "preferred_tokens": [
      { "token": "USDC", "chain": "SOL", "settlement_count": 88, "volume_usd": 4400.00 },
      { "token": "USDT", "chain": "POL", "settlement_count": 25, "volume_usd": 1250.00 }
    ]
  }
}
```

| Field                            | Description                                                                 |
| -------------------------------- | --------------------------------------------------------------------------- |
| `avg_seconds_window_to_settled`  | Average seconds from payment window open to settlement                      |
| `avg_seconds_claimed_to_settled` | Average seconds from customer clicking "I've Paid" to on-chain confirmation |
| `avg_seconds_late_by`            | For late payments — how far past the primary window they arrived (seconds)  |

Use `avg_seconds_late_by` to decide whether to widen your primary payment window. A high `late_rate_pct` with a low `avg_seconds_late_by` (e.g. \< 120 s) indicates customers are consistently on time but the window is slightly too tight.

***

## Webhook Events

| Event                                         | Trigger                                                  |
| --------------------------------------------- | -------------------------------------------------------- |
| `gateway.payment_intent.created`              | Payment link created                                     |
| `gateway.payment.customer_confirmed`          | Customer clicked "I've Made This Payment"                |
| `gateway.payment.settled`                     | Payment confirmed on-chain and merchant balance credited |
| `gateway.payment.paid_late`                   | Settled during the late monitoring window                |
| `gateway.payment.expired`                     | Monitoring window closed without full payment            |
| `gateway.underpayment.reported`               | Customer filed an underpayment report                    |
| `gateway.underpayment.recovery_escalated`     | Merchant escalated the report to Yativo ops              |
| `gateway.underpayment.reversal_queued`        | Merchant approved a refund                               |
| `gateway.underpayment.reconciliation_created` | Merchant created a reconciliatory payment link           |
| `gateway.underpayment.settled_as_paid`        | Merchant settled original intent at revised paid amount  |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Auto-Forwarding" icon="arrow-right-arrow-left" href="/yativo-crypto/auto-forwarding">
    Sweep settled funds to an external wallet automatically.
  </Card>

  <Card title="Webhooks" icon="bell" href="/yativo-crypto/webhooks">
    Full webhook reference and signature verification.
  </Card>

  <Card title="Supported Chains" icon="link" href="/yativo-crypto/supported-chains">
    All chains and tokens available on the platform.
  </Card>

  <Card title="Compliance Screener" icon="shield-check" href="/yativo-crypto/compliance-screener">
    How wallet addresses are screened on the checkout page.
  </Card>
</CardGroup>